{"skill":{"slug":"agent-memory-local","displayName":"Agent Memory Local","summary":"Local-first memory retrieval for Agent/OpenClaw workspaces. Use when the user asks about prior work, decisions, dates, preferences, root causes, todo history...","description":"---\nname: agent-memory-local\ndescription: Local-first memory retrieval for Agent/OpenClaw workspaces. Use when the user asks about prior work, decisions, dates, preferences, root causes, todo history, or \"what changed\" questions and you want explainable retrieval from MEMORY.md + memory/*.md instead of a remote memory platform. Best for Markdown-based long-term memory, local audits, postmortems, and continuity across long-running assistant sessions.\n---\n\n# Agent Memory Local\n\n## Overview\n\nSearch and explain facts from `MEMORY.md` and `memory/*.md` in a local workspace.\n`agent-memory-local` gives an agent a transparent, local-first memory layer for questions like **“我们上次怎么定这个规则的？”** or **“昨天为什么飞书断联？”** without depending on a hosted memory service.\n\nProduction 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.\n\n## Why install this\n\nUse this skill when you want to:\n- find prior decisions, root causes, and preference history from Markdown memory files\n- explain why a result matched instead of trusting a black-box memory API\n- keep retrieval local and rebuild the index inside the workspace\n\nBest fit:\n- local or self-hosted agent setups\n- teams that store durable memory in Markdown\n- users who want transparent, inspectable memory retrieval instead of a black-box cloud memory service\n\n## Common Use Cases\n\n- **Decision recall** — “我们之前怎么定这个规则的？”\n- **Incident review** — “飞书昨天为什么断联了？”\n- **Change tracking** — “更新后为什么记忆搜索变了？”\n- **Preference recall** — “小红书配图策略现在怎么要求？”\n- **Policy / guardrail checks** — “敏感信息能不能写进日志？”\n\n## Quick Start\n\n### 30-second first run\n```bash\npython custom-skills/agent-memory-local/scripts/agent_memory_local.py build-index\npython custom-skills/agent-memory-local/scripts/agent_memory_local.py smart-query \"飞书昨天为什么断联了\" -k 3\n```\n\n### Build the local index\n```bash\npython custom-skills/agent-memory-local/scripts/agent_memory_local.py build-index\n```\n\n### Direct retrieval\n```bash\npython custom-skills/agent-memory-local/scripts/agent_memory_local.py query \"昨天更新后为什么记忆搜索变了\" -k 6\n```\n\n### Smart natural-language retrieval\n```bash\npython custom-skills/agent-memory-local/scripts/agent_memory_local.py smart-query \"飞书昨天为什么断联了\" -k 6\npython 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\n```\n\n### Health check / doctor\n```bash\npython custom-skills/agent-memory-local/scripts/agent_memory_local.py doctor\n```\n\n### Explain why a result matched\n```bash\npython custom-skills/agent-memory-local/scripts/agent_memory_local.py explain \"飞书昨天为什么断联了\" --smart -k 3\npython custom-skills/agent-memory-local/scripts/agent_memory_local.py explain \"Why did Feishu disconnect yesterday?\" --smart -k 3\n```\n\n## Not the best fit\n\nUse a different memory system if you need:\n- graph/relationship-heavy enterprise memory\n- multi-user hosted memory APIs\n- fully managed temporal knowledge graph systems\n\n## Core Capabilities\n\n### 1. Local index build\n- Reads from:\n  - `MEMORY.md`\n  - `memory/learnings.md` (if present)\n  - `memory/YYYY-MM-DD.md`\n- Splits Markdown into retrieval chunks\n- Builds a lightweight hashed vector index into `.memory-index/` under the workspace root\n- Stores freshness metadata for auto-rebuild checks\n\n### 2. Explainable retrieval\nReturns:\n- top matched file + title + snippet\n- overlap count\n- semantic score\n- explain block with overlap terms / anchor hits / recency bonus\n- index freshness status\n- optional `explain` view for cleaner public-facing reasoning output\n\nThis makes it useful when the user asks:\n- “我们上次怎么定这个规则的？”\n- “昨天为什么飞书断联？”\n- “记忆检索主路由是什么时候改的？”\n- “关于这个需求之前有没有决定？”\n\n### 3. Chinese-friendly anchors\nThe retriever is tuned for queries like:\n- `飞书 掉线`\n- `记忆搜索 变了`\n- `主路由 默认入口`\n- `截图 宿主`\n- `duplicate plugin id`\n- `gateway timeout`\n\nIt boosts domain phrases, recency, and strong anchors instead of relying only on generic vector similarity.\n\n### 4. Smart query rewriting\n`smart-query` rewrites and scores multiple candidate queries automatically.\nThis helps with fuzzy questions like:\n- “昨天更新后为什么记忆搜索变了？”\n- “飞书昨天为什么断联？”\n- “主路由后来是不是改过？”\n\n### 5. Optional rerank enhancement\nIf `SILICONFLOW_API_KEY` is available, retrieval can optionally rerank the best candidates via SiliconFlow rerank.\nIf the key is missing, the skill still works locally.\n\n## Example Output\n\nExample command:\n```bash\npython custom-skills/agent-memory-local/scripts/agent_memory_local.py explain \"飞书昨天为什么断联了\" --smart -k 2\n```\n\nExample result shape:\n```json\n{\n  \"query\": \"飞书昨天为什么断联了\",\n  \"used_query\": \"飞书 断联 duplicate plugin id gateway timeout\",\n  \"results\": [\n    {\n      \"rank\": 1,\n      \"file\": \"memory/2026-03-10-request-timed-out-before-a-res.md\",\n      \"score\": 0.5084,\n      \"why_matched\": {\n        \"anchor_hits\": [\"duplicate plugin id\", \"gateway timeout\", \"断联\", \"飞书\"],\n        \"overlap_terms\": [\"duplicate\", \"duplicate plugin id\", \"gateway\", \"gateway timeout\"]\n      }\n    }\n  ]\n}\n```\n\nThis is the point of the skill: not just “some memory results”, but a query rewrite + top hits + an explanation of why they matched.\n\n## Workflow\n\n### Workflow A — answer a memory question\n1. Run `smart-query`\n2. Inspect top 3-5 results and explain fields\n3. Open the source Markdown file if you need exact wording\n4. Answer with the retrieved fact, not with guesswork\n\n### Workflow B — prepare for long-running assistant memory\n1. Keep durable facts in `MEMORY.md` / `memory/*.md`\n2. Run `build-index`\n3. Use `doctor` to confirm index freshness\n4. Use `query` / `smart-query` as the workspace memory route\n\n### Workflow C — debug retrieval quality\n1. Run `doctor`\n2. Confirm workspace detection and index freshness\n3. Rebuild with `build-index`\n4. Retry with `query`\n5. If results are fuzzy, try `smart-query`\n\n## Configuration\n\n### Workspace resolution\nThe scripts resolve the workspace in this order:\n1. `--workspace /path/to/workspace` CLI arg\n2. `AGENT_MEMORY_WORKSPACE` env var\n3. current working directory or its parents\n4. the skill location's parent chain\n\n### Optional env vars\n- `AGENT_MEMORY_WORKSPACE` — force the workspace root\n- `MEMORY_AUTO_REBUILD=0|1` — disable/enable auto rebuild when stale\n- `MEMORY_RERANK=0|1` — disable/enable rerank\n- `SILICONFLOW_API_KEY` — enable rerank enhancement\n\nUse `--workspace` when running outside the target repo and you want deterministic workspace selection.\n\n### Index location\nThe index is stored in `.memory-index/` at the resolved workspace root, not inside the skill folder.\nExamples:\n- workspace `/repo/project` → index at `/repo/project/.memory-index/`\n- workspace `E:/openclaw/.openclaw/workspace` → index at `E:/openclaw/.openclaw/workspace/.memory-index/`\n\n### When to rebuild the index\nRebuild manually when:\n1. first run in a new workspace\n2. `MEMORY.md` or `memory/*.md` changed and you want immediate freshness\n3. `doctor` reports a stale index\n4. retrieval results look outdated or obviously off-topic\n5. you switched workspaces or restored memory files from backup\n\nIf `MEMORY_AUTO_REBUILD=1`, query flows may rebuild automatically when the index is stale.\n\n## Files in this skill\n\n### scripts/\n- `agent_memory_local.py` — top-level CLI entrypoint\n- `build_index.py` — builds `.memory-index/`\n- `retrieve.py` — direct retrieval engine\n- `memory_query.py` — smart rewrite + best-query selector\n- `doctor.py` — health / freshness checker\n- `explain.py` — cleaner explanation view for why results matched\n- `benchmark.py` — regression benchmark runner against representative memory queries\n- `common.py` — workspace and path resolution helpers\n\n### references/\n- `architecture.md` — design notes and tradeoffs\n- `publish-plan.md` — packaging / release checklist for ClawHub\n\n## When to prefer this skill over heavier memory platforms\nUse `agent-memory-local` when you want:\n- local-first memory\n- human-readable Markdown memory source of truth\n- explainable retrieval\n- low dependencies\n- easy audits and backups\n\nPrefer heavier systems (Mem0 / Letta / Graphiti / Zep-style approaches) when you need:\n- hosted memory APIs\n- multi-user context services\n- temporal knowledge graphs\n- relationship-aware graph retrieval\n- enterprise-scale memory orchestration\n","topics":["Agent Memory","Long Term Memory"],"tags":{"latest":"0.1.8","local":"0.1.5","memory":"0.1.5","rag":"0.1.5","retrieval":"0.1.5"},"stats":{"comments":0,"downloads":822,"installsAllTime":31,"installsCurrent":2,"stars":2,"versions":9},"createdAt":1773678516102,"updatedAt":1779001045696},"latestVersion":{"version":"0.1.8","createdAt":1773829933423,"changelog":"Sync latest local fixes and compatibility polish","license":"MIT-0"},"metadata":null,"owner":{"handle":"wangziiiiii","userId":"s17drex5bt1j1qb2b8tyfhtg4583gj72","displayName":"wangziiiiii","image":"https://avatars.githubusercontent.com/u/202627748?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780089956925}}