Tools Reference

Once installed, openclaw-amem exposes five tools to OpenClaw agents.

---

memory_add

Write a new memory to the store.

memory_add(text="Your memory content here.")

Parameters

Parameter	Type	Required	Description
text	string	✅	The content to store as a memory.
subjects	string[]	—	Who this memory is about. Empty means it is about the world or the agent itself and stays visible whoever is present.

What happens internally

1. Exact hash dedup check — skips if identical content already exists
2. High-similarity dedup check (cosine ≥ 0.85) — folds into the existing note instead of creating a duplicate. Between 0.72 and 0.85 the new note is stored but flagged pending_merge
3. LLM note construction — extracts keywords, tags, context summary, category
4. Link generation — finds up to 6 candidates, LLM verifies bidirectional links
5. Memory evolution — updates attributes on up to 3 linked notes
6. Saves to Qdrant with embedding

---

memory_search

Search long-term memories using hybrid retrieval.

memory_search(query="your search query", limit=5)

Parameters

Parameter	Type	Default	Description
query	string	—	Natural language search query.
limit	number	5	Maximum matches to return. Link-expanded notes are appended on top of this, up to 8 more.
topicsFilter	string[]	—	Keep only knowledge notes carrying all of these topics. Memory notes pass through unfiltered, so on a store that is mostly episodic this filters almost nothing.
subject	string	—	Who you are talking to or about. Returns memories that name them plus memories that name nobody.

limit does not read the topK config key

The tool hardcodes 5. topK in openclaw.json is read by the memory-capability path, not by this tool — setting it does not change what memory_search returns.

Returns

An array of memory objects ranked by relevance:

[
  {
    "id": "uuid",
    "content": "Original memory text",
    "context": "One-sentence summary",
    "keywords": ["keyword1", "keyword2"],
    "tags": ["tag1", "tag2"],
    "topics": [],
    "links": ["uuid-of-a-linked-note"],
    "timestamp": "2026-07-31T09:00:00.000Z",
    "note_type": "memory",
    "similarity": 0.842,
    "rrf": 0.0328,
    "via": "match"
  }
]

Field	Meaning
similarity	Cosine similarity to the query, −1 to 1. Not what ordered the list.
rrf	The fused score the matches are sorted by. 0 when no retriever ranked this note.
via	match — retrieved for the query. link — not retrieved; here because it links to one that was.

via is the field to read when a result looks unrelated. The tool appends link-expanded notes after the matches in discovery order. These notes were never ranked. Their position carries no meaning. They appear because the graph connects them to a note that matched.

Retrieval pipeline

1. Embeds query locally (ONNX)
2. BM25 ranking with Jieba tokenization for Chinese — only notes that share a term with the query; a note the query never hits contributes nothing
3. Dense vector cosine similarity search
4. RRF fusion (k=60)
5. Heat boost: rrf × (1 + 0.05 × ln(1+count) / (age_days+1))
6. 2-hop BFS graph expansion with cos-sim ≥ 0.25 gate, appended as via: "link"

---

memory_list

Return the total count of active memories for the current agent.

memory_list()

Returns

{ "count": 42 }

---

memory_consolidate

Manually trigger semantic deduplication and link cascading across the whole store.

memory_consolidate()

The system also runs this automatically at 02:30 AM daily. Use this tool to trigger it on demand, for example after a bulk import.

What it does

1. Groups all active notes by category
2. Finds pairs with cosine similarity ≥ 0.75 within each group
3. Merges duplicates into a unified note via LLM
4. Soft-deletes (is_active: false) merged source notes
5. Cascades all link references from deleted notes to the merged note