Skill: wangziiiiii/agent-memory-local (version 0.1.8)

--- name: agent-memory-local description: 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. --- # 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


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)