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

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

python custom-skills/agent-memory-local/scripts/agent_memory_local.py build-index

Direct retrieval

python custom-skills/agent-memory-local/scripts/agent_memory_local.py query "昨天更新后为什么记忆搜索变了" -k 6

Smart natural-language retrieval

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

python custom-skills/agent-memory-local/scripts/agent_memory_local.py doctor

Explain why a result matched

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:

python custom-skills/agent-memory-local/scripts/agent_memory_local.py explain "飞书昨天为什么断联了" --smart -k 2

Example result shape:

{
  "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

Run smart-query
Inspect top 3-5 results and explain fields
Open the source Markdown file if you need exact wording
Answer with the retrieved fact, not with guesswork

Workflow B — prepare for long-running assistant memory

Keep durable facts in MEMORY.md / memory/*.md
Run build-index
Use doctor to confirm index freshness
Use query / smart-query as the workspace memory route

Workflow C — debug retrieval quality

Run doctor
Confirm workspace detection and index freshness
Rebuild with build-index
Retry with query
If results are fuzzy, try smart-query

Configuration

Workspace resolution

The scripts resolve the workspace in this order:

--workspace /path/to/workspace CLI arg
AGENT_MEMORY_WORKSPACE env var
current working directory or its parents
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:

first run in a new workspace
MEMORY.md or memory/*.md changed and you want immediate freshness
doctor reports a stale index
retrieval results look outdated or obviously off-topic
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