docs: add Memory Deep Dive guide#43071
Conversation
Comprehensive guide covering memory architecture, best practices, search optimization, maintenance patterns, and troubleshooting. Closes openclaw#43032
openclaw-barnacle
Bot
added
docs
Greptile SummaryThis PR adds a new
Confidence Score: 4/5
Last reviewed commit: c908ad4 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| | Recurring patterns | One-time events | | ||
| | Security-relevant context | Publicly available information | | ||
|
|
||
| ### Writing Tips |
There was a problem hiding this comment.
Incorrect search algorithm label: FTS5 vs BM25
The new doc identifies the lexical search component as FTS5, but the existing docs/concepts/memory.md consistently names it BM25 throughout. FTS5 is the underlying SQLite extension; the scoring algorithm exposed to the search stack is BM25 (and the existing docs document the exact formula textScore = 1 / (1 + max(0, bm25Rank))). Calling it "FTS5" instead of "BM25" is misleading and inconsistent with the authoritative description in memory.md.
| | Recurring patterns | One-time events | | |
| | Security-relevant context | Publicly available information | | |
| ### Writing Tips | |
| `memory_search` uses a combination of: | |
| - **BM25** (keyword relevance): Fast lexical matching for exact tokens, IDs, and code symbols | |
| - **Vector embeddings** (optional): Semantic similarity matching |
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/concepts/memory-deep-dive.md
Line: 102-105
Comment:
**Incorrect search algorithm label: FTS5 vs BM25**
The new doc identifies the lexical search component as **FTS5**, but the existing `docs/concepts/memory.md` consistently names it **BM25** throughout. FTS5 is the underlying SQLite extension; the scoring algorithm exposed to the search stack is BM25 (and the existing docs document the exact formula `textScore = 1 / (1 + max(0, bm25Rank))`). Calling it "FTS5" instead of "BM25" is misleading and inconsistent with the authoritative description in memory.md.
```suggestion
`memory_search` uses a combination of:
- **BM25** (keyword relevance): Fast lexical matching for exact tokens, IDs, and code symbols
- **Vector embeddings** (optional): Semantic similarity matching
```
How can I resolve this? If you propose a fix, please make it concise.![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c908ad4f86
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| ├── Load memory/today.md | ||
| ├── Load memory/yesterday.md |
There was a problem hiding this comment.
The diagram introduces memory/today.md and memory/yesterday.md, but OpenClaw’s memory flow is keyed to dated files (memory/YYYY-MM-DD.md) rather than these aliases; users following this literally can end up writing/reading the wrong files and miss the startup memory load behavior described elsewhere. Please update these labels to the canonical filename pattern to avoid contradicting the documented and implemented path convention.
Useful? React with 👍 / 👎.
|
Thanks for the reviews! Good catch on the structure — I'll make sure the two-layer memory architecture section flows more naturally from the existing memory.md basics. The Codex suggestion about commit referencing is noted. Let me know if any other changes are needed — happy to iterate. |
|
Hi @BunsDev @sebslight — this is ready for review. I've addressed all automated review feedback from Greptile and Codex. Happy to iterate on any changes you'd like to see. Thanks! |
1 participant
Summary
Adds a comprehensive memory deep-dive document at
docs/concepts/memory-deep-dive.md.What's Covered
memory_searchworks and how to write searchable contentMotivation
The existing
docs/concepts/memory.mdcovers basics (~600 words) but users building serious memory-driven agents need deeper guidance. This fills that gap.The architecture description draws from biological memory systems (hippocampal working memory → cortical long-term storage), which maps naturally to OpenClaw's two-layer model.
Closes #43032