agent-memory-local
# Agent Memory Local
## Overview
Search and explain facts from `MEMORY.md` and `memory/*.md` in a local workspace.
`agent-memory-local` gives an agent a transparent, local-first memory layer for questions like **“我们上次怎么定这个规则的？”** or **“昨天为什么飞书断联？”** without depending on a hosted memory service.
Production note: this retrieval style has already been used in real OpenClaw operating workflows behind **jisuapi.com** and **jisuepc.com**. That is a proof point, not a dependency.
## Why install this
Use this skill when you want to:
- find prior decisions, root causes, and preference history from Markdown memory files
- explain why a result matched instead of trusting a black-box memory API
- keep retrieval local and rebuild the index inside the workspace
Best fit:
- local or self-hosted agent setups
- teams that store durable memory in Markdown
- users who want transparent, inspectable memory retrieval instead of a black-box cloud memory service
## Common Use Cases
- **Decision recall** — “我们之前怎么定这个规则的？”
- **Incident review** — “飞书昨天为什么断联了？”
- **Change tracking** — “更新后为什么记忆搜索变了？”
- **Preference recall** — “小红书配图策略现在怎么要求？”
- **Policy / guardrail checks** — “敏感信息能不能写进日志？”
## Quick Start
### 30-second first run
```bash
python custom-skills/agent-memory-local/scripts/agent_memory_local.py build-index
python custom-skills/agent-memory-local/scripts/agent_memory_local.py smart-query "飞书昨天为什么断联了" -k 3
```
### Build the local index
```bash
python custom-skills/agent-memory-local/scripts/agent_memory_local.py build-index
```
### Direct retrieval
```bash
python custom-skills/agent-memory-local/scripts/agent_memory_local.py query "昨天更新后为什么记忆搜索变了" -k 6
```
### Smart natural-language retrieval
```bash
python custom-skills/agent-memory-local/scripts/agent_memory_local.py smart-query "飞书昨天为什么断联了" -k 6
python custom-skills/agent-memory-local/scripts/agent_memory_local.py smart-query "What changed in our memory retrieval route after yesterday's update?" -k 6
```
### Health check / doctor
```bash
python custom-skills/agent-memory-local/scripts/agent_memory_local.py doctor
```
### Explain why a result matched
```bash
python custom-skills/agent-memory-local/scripts/agent_memory_local.py explain "飞书昨天为什么断联了" --smart -k 3
python custom-skills/agent-memory-local/scripts/agent_memory_local.py explain "Why did Feishu disconnect yesterday?" --smart -k 3
```
## Not the best fit
Use a different memory system if you need:
- graph/relationship-heavy enterprise memory
- multi-user hosted memory APIs
- fully managed temporal knowledge graph systems
## Core Capabilities
### 1. Local index build
- Reads from:
- `MEMORY.md`
- `memory/learnings.md` (if present)
- `memory/YYYY-MM-DD.md`
- Splits Markdown into retrieval chunks
- Builds a lightweight hashed vector index into `.memory-index/` under the workspace root
- Stores freshness metadata for auto-rebuild checks
### 2. Explainable retrieval
Returns:
- top matched file + title + snippet
- overlap count
- semantic score
- explain block with overlap terms / anchor hits / recency bonus
- index freshness status
- optional `explain` view for cleaner public-facing reasoning output
This makes it useful when the user asks:
- “我们上次怎么定这个规则的？”
- “昨天为什么飞书断联？”
- “记忆检索主路由是什么时候改的？”
- “关于这个需求之前有没有决定？”
### 3. Chinese-friendly anchors
The retriever is tuned for queries like:
- `飞书 掉线`
- `记忆搜索 变了`
- `主路由 默认入口`
- `截图 宿主`
- `duplicate plugin id`
- `gateway timeout`
It boosts domain phrases, recency, and strong anchors instead of relying only on generic vector similarity.
### 4. Smart query rewriting
`smart-query` rewrites and scores multiple candidate queries automatically.
This helps with fuzzy questions like:
- “昨天更新后为什么记忆搜索变了？”
- “飞书昨天为什么断联？”
- “主路由后来是不是改过？”
### 5. Optional rerank enhancement
If `SILICONFLOW_API_KEY` is available, retrieval can optionally rerank the best candidates via SiliconFlow rerank.
If the key is missing, the skill still works locally.
## Example Output
Example command:
```bash
python custom-skills/agent-memory-local/scripts/agent_memory_local.py explain "飞书昨天为什么断联了" --smart -k 2
```
Example result shape:
```json
{
"query": "飞书昨天为什么断联了",
"used_query": "飞书 断联 duplicate plugin id gateway timeout",
"results": [
{
"rank": 1,
"file": "memory/2026-03-10-request-timed-out-before-a-res.md",
"score": 0.5084,
"why_matched": {
"anchor_hits": ["duplicate plugin id", "gateway timeout", "断联", "飞书"],
"overlap_terms": ["duplicate", "duplicate plugin id", "gateway", "gateway timeout"]
}
}
]
}
```
This is the point of the skill: not just “some memory results”, but a query rewrite + top hits + an explanation of why they matched.
## Workflow
### Workflow A — answer a memory question
1. Run `smart-query`
2. Inspect top 3-5 results and explain fields
3. Open the source Markdown file if you need exact wording
4. Answer with the retrieved fact, not with guesswork
### Workflow B — prepare for long-running assistant memory
1. Keep durable facts in `MEMORY.md` / `memory/*.md`
2. Run `build-index`
3. Use `doctor` to confirm index freshness
4. Use `query` / `smart-query` as the workspace memory route
### Workflow C — debug retrieval quality
1. Run `doctor`
2. Confirm workspace detection and index freshness
3. Rebuild with `build-index`
4. Retry with `query`
5. If results are fuzzy, try `smart-query`
## Configuration
### Workspace resolution
The scripts resolve the workspace in this order:
1. `--workspace /path/to/workspace` CLI arg
2. `AGENT_MEMORY_WORKSPACE` env var
3. current working directory or its parents
4. the skill location's parent chain
### Optional env vars
- `AGENT_MEMORY_WORKSPACE` — force the workspace root
- `MEMORY_AUTO_REBUILD=0|1` — disable/enable auto rebuild when stale
- `MEMORY_RERANK=0|1` — disable/enable rerank
- `SILICONFLOW_API_KEY` — enable rerank enhancement
Use `--workspace` when running outside the target repo and you want deterministic workspace selection.
### Index location
The index is stored in `.memory-index/` at the resolved workspace root, not inside the skill folder.
Examples:
- workspace `/repo/project` → index at `/repo/project/.memory-index/`
- workspace `E:/openclaw/.openclaw/workspace` → index at `E:/openclaw/.openclaw/workspace/.memory-index/`
### When to rebuild the index
Rebuild manually when:
1. first run in a new workspace
2. `MEMORY.md` or `memory/*.md` changed and you want immediate freshness
3. `doctor` reports a stale index
4. retrieval results look outdated or obviously off-topic
5. you switched workspaces or restored memory files from backup
If `MEMORY_AUTO_REBUILD=1`, query flows may rebuild automatically when the index is stale.
## Files in this skill
### scripts/
- `agent_memory_local.py` — top-level CLI entrypoint
- `build_index.py` — builds `.memory-index/`
- `retrieve.py` — direct retrieval engine
- `memory_query.py` — smart rewrite + best-query selector
- `doctor.py` — health / freshness checker
- `explain.py` — cleaner explanation view for why results matched
- `benchmark.py` — regression benchmark runner against representative memory queries
- `common.py` — workspace and path resolution helpers
### references/
- `architecture.md` — design notes and tradeoffs
- `publish-plan.md` — packaging / release checklist for ClawHub
## When to prefer this skill over heavier memory platforms
Use `agent-memory-local` when you want:
- local-first memory
- human-readable Markdown memory source of truth
- explainable retrieval
- low dependencies
- easy audits and backups
Prefer heavier systems (Mem0 / Letta / Graphiti / Zep-style approaches) when you need:
- hosted memory APIs
- multi-user context services
- temporal knowledge graphs
- relationship-aware graph retrieval
- enterprise-scale memory orchestration
标签
skill
ai
