README: document the architecture with diagrams - #2
Conversation
Replaces the prose "How it works" bullets with an Architecture section that shows where MCP actually sits: a stdio server each agent launches, with the CLI and Python API as alternative entry points onto the same engine. - System diagram: agents -> MCP/CLI/API -> context guards -> MemoryStore -> embedder, token counter, store.json. - Module map table, so a reader can find the file behind each box. - Recall path: embed, rank, drop below the relevance floor, greedily pack under the token budget. - Write path: the lock/merge/atomic-replace sequence that lets two agents share one file without losing each other's memories. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
![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: 037480f848
ℹ️ About Codex in GitHub
Your team has set up Codex to 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 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| EMB["Embedder — embeddings.py<br/>HashingEmbedder default, offline<br/>SentenceTransformer optional"] | ||
| TOK["Token counter — tokens.py<br/>tiktoken, or an approximation"] | ||
| DISK[("store.json<br/>one file per project<br/>lock · merge · atomic replace")] |
There was a problem hiding this comment.
When the tool is used from multiple repositories, no project scoping creates this “one file per project” topology: both the CLI and MCP server default to the single ~/.agent_memory/store.json path, and the setup examples above hard-code that same path. Users following this architecture literally will therefore mix unrelated memories and handoffs across projects; document that each project must configure a distinct AGENT_MEMORY_PATH, or add actual project namespacing.
Useful? React with 👍 / 👎.
1 participant
Replaces the prose "How it works" bullets with an Architecture section that shows where MCP actually sits.
What's new
System diagram — agents → MCP server (stdio) / CLI / Python API → context guards →
MemoryStore→ embedder, token counter,store.json. MCP is drawn as the integration surface it is: a stdio server each agent launches as a subprocess, with the CLI and Python API as alternative entry points onto the same engine.Module map — a table pairing each box with the file behind it, so a reader can go from diagram to code.
Recall path — embed, rank by cosine, drop anything below the relevance floor, greedily pack under the token budget. Makes explicit why the guards sit between the tools and the store: tool output hides scores, so the agent can't judge relevance itself.
Write path — the lock → re-read → atomic-replace sequence, as a sequence diagram showing two agents contending for the same file. Documents the durability properties fixed in #1: no lost updates, no torn files, fresh reads, compact storage.
Verified
All four mermaid blocks render on GitHub — the viewscreen iframes resize from the 180px placeholder to 377/756/190/570px, with no syntax errors in the DOM. Checked on this branch before merging.
🤖 Generated with Claude Code