Do you know the mechanism for adding a "second brain" to Codex so that context remains even if the conversation is interrupted? Its name is Agentmemory. I've summarized everything from its installation procedure and configuration to common pitfalls. This is a must-read for those who find it tedious to explain the same thing every time and those who don't want to waste tokens.
Every morning, I start Claude Code and type "Continue from yesterday," only to be met with "Please tell me the contents of the previous session." This is a phenomenon that happens almost every day.
The moment a session is cut, the project context is reset. While things written in CLAUDE.md are read, the "weight of context"—such as discussions about a bug from three days ago or the reasoning behind a design policy decided last week—disappears entirely.
One developer wrote:
only 30 days of your Claude Code session history is saved on your computer by default, you have to set that longer if you want to have memory over all of them.
The default retention period for session history is 30 days. Moreover, what's saved is just a "record as a string," not a mechanism that can be called up as context.
It's basically the same on the Codex side. GPT-5.5's context is 1M tokens via API and 400K in Codex CLI. The physical size seems sufficient, but in practice, accuracy begins to drop around 200K tokens.
That's when Agentmemory, which made headlines after surpassing 4,000 Stars, arrived. I've been using it heavily for a week. Here is my conclusion:
The expression "adding infinite memory" to Codex/Claude Code is half hyperbole and half truth.
In this article, I will explain how to maximize the "truth" part and how to avoid the "hyperbole" part when you encounter it.
1. Why Do Codex/Claude Code Get "Amnesia"?
Before discussing Agentmemory, let me clarify why existing tools aren't enough. If we skip this, it just ends with "I added a convenient memory tool," and we miss the essence.
Even if the context window is large, it cannot be fully utilized in practice.
As of May 2026, the context windows of major models are as follows:
● Claude Opus 4.7: 1M tokens (expanded from 200K)
● GPT-5.5: 1M tokens (API) / 400K limit in Codex CLI
● Gemini 3.1 Pro: 1M tokens
In Japanese terms, this is about 1.41 million characters. It's enough capacity to fit not just one book, but an entire series. Looking at the numbers, it seems like "everything fits."
However, Anthropic itself wrote in its official engineering blog:
As the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases.
Physical capacity does not equal the ability to maintain accuracy. Experience shows that around 200K to 400K tokens, Claude starts to "forget what it just said." This is commonly known as context rot.
"Collapse of Thought" that occurred even in the official Claude Code
Let me give a real example. On April 23, 2026, Anthropic officially released a postmortem.
A bug rolled out on March 26 caused the "feature to clear old thoughts after 1 hour of idle time" to fire every turn even after resuming a session.
As a result, the median visible thinking length changed as follows:
● January: 2,200 characters
● March: 600 characters
A 73% collapse. For about a month, the official Claude Code was arbitrarily cutting its own context.
This is important because it shows that context rot isn't just a "user error" but can also happen due to service-side circumstances. No matter how cleanly you write CLAUDE.md, a single tuning adjustment on the tool side can turn "last week's context" into scrap paper.
Limits of existing solutions (CLAUDE.md / auto-memory)
Anthropic is taking measures. Claude Code's auto-memory feature is a mechanism that remembers what was learned between sessions and recalls it upon restart. The Claude Code team announced this in May.
However, this is structured to work in tandem with compaction. It performs an internal flow of "compressing context → moving important information to memory," and the AI decides "what to keep" during each compression. Users cannot touch this decision logic.
Furthermore, auto-memory is exclusive to Claude Code. There is no API to read it from other agents like Codex, Cursor, Cline, or Hermes. For those using multiple agents, the situation where you have to "explain the same premise three times" becomes normalized.
2. How Agentmemory is Different
Now for the main topic. Agentmemory (official repo: rohitg00/agentmemory) is an open-source memory engine that reached 8.8k Stars as of May 15, 2026. It has more than doubled since the initial report of "4,000+ Stars." It is Apache 2.0 licensed, TypeScript-based, and the latest release is v0.9.12 (May 13). It is completely self-hosted with zero data sent to external SaaS.
Developer's Philosophy
Lead developer Rohit Ghumare (@ghumare64) summarized the essence of Agentmemory in one sentence:
Built this 6 months ago with agentmemory: persistent memory for AI coding agents. Same core idea: stop re-deriving, start compiling.
"Stop re-deriving, start compiling." This is the philosophical difference from existing tools.
CLAUDE.md was "input for re-deriving every time." Project structure, conventions, past decisions. The AI would re-read, re-interpret, and then forget them every session. Agentmemory changes this by replacing the "re-derivation loop" with a "compiled memory layer."
3-Tier Architecture (Summary from README)
According to the official README, the internal structure is divided into three stages:
First is Capture. It uses 12 Claude Code lifecycle hooks to capture data automatically, so there's no need to manually run memory_save.
Second is Pipeline. It organizes observations through a flow of deduplication → privacy filter (automatic removal of API keys/PII) → AI-based compression.
Third is Retrieval. It fuses three types of hybrid search (BM25 / vector / graph) using RRF k=60. BM25 handles stemming keywords and synonym expansion, vector handles cosine similarity of dense embeddings, and graph handles knowledge graph traversal. By fusing them with Reciprocal Rank Fusion, if one method misses something, the other picks it up. Results are returned with session dispersion (max 3 per session), solving the problem of getting results only from the same session.
4-tier memory (Inspired by Ebbinghaus)
Another interesting aspect is the design that divides memory into four tiers that "grow" over time.
The bottom tier is Working, which is short-term memory like raw tool execution observations, error logs, and command history. Moving up to Episodic, it becomes session summaries of "what happened." At the Semantic level, it turns into "what I know," extracted knowledge, and patterns. The top tier is Procedural, which consists of workflows and procedures on "how to proceed."
Frequently accessed memories are strengthened, while unreferenced memories decay according to the Ebbinghaus forgetting curve. It's a mechanism modeled after human memory structure. This is the true nature of "stop re-deriving and start compiling."
Positioning Against Competitors
To be honest, looking only at GitHub Stars, Agentmemory is still small compared to competitors.
● Mem0: 55.7k Stars, general-purpose memory layer, API/Cloud first
● Letta (formerly MemGPT): 22.7k Stars, agent OS, virtual context management
● Agentmemory: 8.8k Stars, specialized for coding agents, local SQLite
It loses in a numbers game. However, where Agentmemory shines is its specialization for coding agents and decoupled design. Rohit himself wrote:
If you want actual extended memory architecture, cross-agent, portable, not locked to a particular agent, check out agentmemory. It's designed as a decoupled memory layer that works across harnesses.
You can connect to Cursor, Cline, Claude Code, Codex, and Hermes using the same memory. This is the differentiation from Mem0 and Letta. Mem0 is too general and has weak automatic capture for coding contexts, while Letta is an agent OS, making it hard to extract just the memory layer.
Agentmemory hits the bullseye for the niche of "developers using multiple coding agents simultaneously."
3. Starting in 3 Minutes — Installation and Initial Setup
Let's get hands-on. The basic flow is the same for Mac, Linux, and Windows, as long as you have a Node.js environment.
Step 1: Start the Memory Server
Just open a terminal and run this:
Start the memory server (keep it running)
npx @agentmemory/agentmemory
The first time takes 1-2 minutes to download dependencies. Once successful, a REST API will start at http://localhost:3111. You can check the health with:
curl http://localhost:3111/agentmemory/health
→ {"status":"ok","version":"0.9.12"}
A viewer also starts up, so you can visualize the memory content by opening http://localhost:3113 in your browser.
Step 2: Insert Demo Data
It's hard to visualize with empty content, so let's add sample data.
Run in a separate terminal
npx @agentmemory/agentmemory demo
This writes dummy session history to SQLite, making it observable in the viewer.
Step 3: Integrate into Claude Code
The fastest way from the Claude Code side is via the plugin marketplace.
Execute within Claude Code
/plugin marketplace add rohitg00/agentmemory
/plugin install agentmemory
This automatically registers the following:
● 12 hooks (all lifecycles including SessionStart / PostToolUse / Stop)
● 4 skills (recall / consolidate / export / governance)
● 51 MCP tools (AGENTMEMORY_TOOLS=all for everything, default is 15 core tools)
Step 4: Integrate into Codex CLI
Codex follows a similar style.
codex plugin marketplace add rohitg00/agentmemory
codex plugin install agentmemory
For Codex, AGENTMEMORY_URL=http://localhost:3111 is automatically set as an environment variable. Note that Codex is stricter about MCP synchronicity than Claude Code, so it will error out immediately if the server is down. Don't forget to keep it running.
Step 5: Connect to Cursor / Cline, etc.
To use it via Cursor, add it to ~/.cursor/mcp.json:
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": { "AGENTMEMORY_URL": "http://localhost:3111" }
}
}
}
Cline, Hermes, and other MCP-compatible editors connect in the same pattern. There is a trap where Cursor's MCP settings aren't reflected just by closing and reopening; I'll detail this in the "5 Pitfalls" section.
Step 6: Health Check Ritual
After setup, here is the mandatory checklist:
1. Memory server connectivity
curl http://localhost:3111/agentmemory/health
2. Check iii-engine version (v0.11.2 required)
iii --version
3. Check memory in the viewer
If you see observations recorded in the viewer, the setup is successful. If Node.js is already installed, it takes less than 3 minutes.
4. The 3 Basic Actions — Save, Search, Auto-Compress
Agentmemory usage can be organized into three main actions.
Action 1: Save (Automatic Capture is the Default)
In Mem0 or Letta, it's normal to save using manual commands like memory_add(...). Agentmemory has a different philosophy: it captures everything automatically using 12 hooks.
For example, the following observations are recorded without you doing anything:
● Commands and output during Bash tool execution (PostToolUse hook)
● Diffs before and after file editing (PreToolUse / PostToolUse hook)
● Automatic injection of related memory at session start (SessionStart hook)
● Summary compression at session end (Stop hook)
The greatest value is that the "burden of the user deciding what to save" becomes zero. While we used to think "this is important, let's write it down" or "let's delete this" in CLAUDE.md, the idea here is to leave that decision logic to the AI.
You can also save manually. By calling memory_save via an MCP tool, you can explicitly mark "this is important." It's safer to manually save critical design decisions rather than relying solely on automatic capture.
Action 2: Search (3-System Hybrid + RRF)
Searching is done via MCP tools or by hitting the REST API directly. Here are the representative MCP tools:
● memory_recall — Retrieve related memory using natural language
● memory_smart_search — Full-featured version of hybrid search
● memory_sessions — List by session
● memory_timeline — Sort by time
● memory_relations — Graph traversal of related entities
If hitting the REST API directly:
Search for "previous fix regarding Supabase auth"
curl -X POST http://localhost:3111/agentmemory/search \
-H "Content-Type: application/json" \
-d '{"query": "supabase auth fix", "limit": 5}'
The results returned are a fusion of BM25 / vector / graph using RRF k=60. Latency is under 20ms at P50 (fast because it's local SQLite).
Accuracy in official benchmarks (LongMemEval-S, 500 questions, ICLR 2025) is as follows:
● R@5: 95.2% (Probability that the correct answer is in the top 5 candidates)
● R@10: 98.6%
● MRR: 88.2%
Note that this is "search accuracy," not "end-to-end QA accuracy." It's the probability that the correct answer is somewhere in the candidates; whether Claude uses it to answer correctly is a separate issue. Don't over-rely on it by confusing the two.
Action 3: Auto-Compression (Growing 4 Tiers Over Time)
Every time the Stop hook runs, three stages of compression occur in order:
First, Working → Episodic collapses raw tool logs into session summaries. Next, Episodic → Semantic extracts "patterns" and "knowledge" from multiple session events. Finally, Semantic → Procedural solidifies frequently repeated steps into "workflows."
This automatically solves the problem of "saving everything and creating search noise." The token budget injected at session start is 2,000 tokens by default. This is designed to restore the "previous context" in a necessary and sufficient form.
5. Workflow for Dual-Wielding Codex / Claude Code
Now for practical application. For those who seriously use both Codex and Claude Code, here are three workflow patterns.
Pattern 1: Daily Flow for Solo Development
By keeping the agentmemory server running, the SessionStart hook fires when Claude Code starts, automatically injecting the previous day's Episodic memory. Even without saying "Continue from yesterday," the conversation starts with Claude already understanding "Let's continue the discussion about being stuck on Supabase RLS."
During coding, the PostToolUse hook keeps writing commands, outputs, and diffs to SQLite. When the session is closed, the Stop hook compresses Working into Episodic. The next morning, that is automatically read, completing the loop.
Pattern 2: Managing Multiple Projects
Agentmemory can divide memory into three scopes. The user scope is tied to the individual, containing "personal habits" like coding convention preferences. The project scope is managed separately for each project, with separate SQLite files. The local scope remains only on that machine and doesn't go out even in team sharing mode.
By changing the environment variable to AGENTMEMORY_PROJECT=foo-app when switching projects, a different SQLite file is referenced. This is incredibly effective for people running multiple projects in parallel. The phenomenon where design decisions from Project A bleed into discussions for Project B happened often with CLAUDE.md. With Agentmemory, they are physically separated, so there's no cross-talk.
Pattern 3: Team Sharing and Joint Development with Listed Companies
We are currently co-developing AI agents with listed companies, and the MCP server sharing mode is subtly effective here. By setting the collab=true flag, multiple Codex / Claude Code instances can reference the same memory server.
Server side
AGENTMEMORY_COLLAB=true npx @agentmemory/agentmemory --bind 0.0.0.0
By referencing it via a team VPN, multiple people can work while sharing the "memory of the same project." However, the privacy filter must be set strongly. If API keys or personal information get mixed in, they will be shared with the whole team, so exclusion settings in .agentmemoryignore are mandatory. I'll touch on this in the "Pitfalls" section.
Pitfalls Unique to Dual-Wielding
When switching between Codex and Claude Code on the same project, memory is shared, but prompt syntax is different. Claude Code's /plugin command doesn't work in Codex, and Codex's codex plugin install doesn't work in Claude Code. Even if it's a "tool that works for both," settings are required individually. Many people get stuck here in the first week.
6. How to Read Benchmarks — Translating Numbers into "Experience"
I'll translate the official numbers into practical sensations.
The Truth Behind "92% Token Reduction"
The "92% reduction" touted in news flashes and Medium articles is on a per-session basis.
● Conventional CLAUDE.md manual operation: approx. 22,000 tokens per session
● Via Agentmemory: approx. 1,900 tokens per session
● Reduction rate: approx. 91-92%
The context injection tokens at the start of a session are drastically reduced. On an annual basis, the numbers change, and the Token Savings table in the README says:
● LLM-summarized operation: approx. 650K tokens / yr (approx. $500 / yr)
● Agentmemory: approx. 170K tokens / yr (approx. $10 / yr)
In terms of tokens, it's about a 74% reduction, but in terms of cost, it's a 98% reduction. $500 becomes $10. The reason for the difference is that Agentmemory runs on local SQLite + local embeddings. Unlike Mem0 or Letta, which run LLM-based compression every time, the operating cost is minimal.
What "LongMemEval-S R@5 95.2%" Means
LongMemEval-S is a long-term memory benchmark released at ICLR 2025 (500 questions, approx. 48 sessions per question, approx. 115K tokens of context). Comparing major tools:
Tool | R@5 |
|---|---|
Agentmemory | 95.2% |
Mem0 (New algorithm, April 2026) | 94.8% |
Letta | 83.2% |
Cognee | 72.5% |
Zep | 71.0% |
Mem0 (Old algorithm) | 68.5% |
Mem0 is closing in with its new algorithm, so it's not fair to call it a "landslide victory" based on numbers alone. However, since Agentmemory achieves 95.2% in combination with an automatic capture mechanism specialized for coding agents, the current evaluation is that it sits in a great spot for the "accuracy vs. operational load" trade-off.
To reiterate, R@5 is search accuracy, not the probability that Claude or Codex will ultimately give the correct answer. Confusing these leads to overvaluation.
Codex 400K vs Opus 4.7 1M: "Physical vs. Practical"
Looking at benchmark numbers, I noticed another important point.
Claude Opus 4.7 expanded its context to 1M tokens. GPT-5.5 is also 1M tokens via API. Looking at this alone, it seems like "we don't need memory tools anymore."
However, Codex CLI is actually limited to 400K. The physical limit and the practical limit are misaligned. Furthermore, as Anthropic itself wrote, context rot begins at 200K-400K tokens as context increases.
In other words, even if physical size increases, the need for a memory engine does not decrease. Rather, "how to efficiently use a wide context window" has become a new technical challenge.
7. 5 Pitfalls — Landmines I Actually Stepped On
I'll be honest here. Here are 5 landmines I stepped on while actually running it, which don't appear in the official README or influencer tweets. I've picked only reproducible ones from GitHub Issues.
Pitfall 1: iii-engine v0.11.2 Version Mismatch
Immediately after setup, some people get this error:
iii: command not found
Or
Version mismatch: expected v0.11.2, got v0.11.0
Agentmemory depends internally on a binary called iii-engine, and the version is pinned to v0.11.2. If another version is already installed, it fails at the startup stage. The workaround is to fetch the fixed version from releases for each OS.
macOS arm64
curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz \
chmod +x ~/.local/bin/iii
Linux x64
curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-x86_64-unknown-linux-gnu.tar.gz \
Verification
iii --version # Should show v0.11.2
If you skip this, everything else will fail later, so get this through first.
Pitfall 2: Issue #181 — Ghost Session Mass Production via Infinite Loop
This one is seriously dangerous. A fatal bug reported in v0.9.1 where calling /summarize from the Stop hook without an API key set causes infinite child session generation.
Stop hook → /summarize → Child session generated
↓
Child session's Stop hook also fires → /summarize → More child sessions
↓
(Infinite loop)
There's a report in GitHub Issue #181 that about 579 ghost sessions were generated in a few minutes. There are three workarounds:
Option 1: Disable agent-sdk mode (Recommended)
export AGENTMEMORY_ALLOW_AGENT_SDK=false
Option 2: Force error with a fake API key
export AGENTMEMORY_ANTHROPIC_API_KEY="fake-key"
Option 3: Set a real API key
export AGENTMEMORY_ANTHROPIC_API_KEY="sk-ant-..."
For production use, Option 1 or 3 is safe. Option 2 is only for the first day when you "just want to get it moving."
Pitfall 3: Issue #159 — MCP and REST API Running on Separate KVs
This is another phenomenon that leaves you scratching your head if you don't know it. Calling an MCP tool (like memory_search) returns empty results every time, yet the REST API (POST /agentmemory/search) finds hits with the same data.
REST API: GET /agentmemory/sessions → 69 observations
MCP tool: memory_sessions → [] (empty)
The cause is that the @agentmemory/mcp package and the Agentmemory server are designed to have completely separate KV stores (Issue #159). MCP is "local KV" and the server is "another KV," with no communication code path between them. As of May 2026, the issue remains open. Workarounds are:
● Option 1: Use the REST API directly (via curl or fetch instead of MCP tools)
● Option 2: Temporarily disable the /mcp hook and run server-only
There are plans to fix this in the future, but for now, you have to build around this specification.
Pitfall 4: MCP Not Reflected in Cursor / VSCode
You edited ~/.cursor/mcp.json and restarted Cursor, but Agentmemory doesn't appear in /mcp list. This happens not just with Cursor but with Windows Store apps in general.
Closing with the GUI "X" button leaves the WindowsApps background process running by default. The old process continues to run with the old settings held in memory. A ritual for complete termination is required.
macOS
pkill -9 Cursor
open /Applications/Cursor.app
Windows (PowerShell)
→ Restart
If you make "checking for residual processes" your default before doubting the config file, you'll save time here.
Pitfall 5: Observations Silently Dropped by Privacy Filter
The phenomenon where "the server is running, but observations don't appear in the viewer" also happens often in the first week. Looking at the logs, you'll see warnings like this:
[warn] observation dropped: private_tag detected
[warn] observation dropped: private_email detected
This is by design, not a bug. Agentmemory's privacy filter automatically detects API keys, passwords, email addresses, and PII, and discards those observations without recording them. It's a great feature for security, but if you don't know about it, you'll think it's "not working." The coexistence strategy is:
Exclude by file using .agentmemoryignore
echo ".env" >> .agentmemoryignore
echo ".env.local" >> .agentmemoryignore
echo "*/.key" >> .agentmemoryignore
echo "*/password*" >> .agentmemoryignore
Especially when running experimental code that includes API keys in observations, it's safe to place this file in advance.
8. Summary — "Infinite Memory" is Not Just Context Window Expansion
After using Agentmemory heavily for a week, this is the feeling that clicked most: The expression "infinite memory" isn't about the physical expansion of the context window.
Even if it increases to 1M tokens, if accuracy drops at 200K, it's ultimately meaningless. I feel the physical size race is already over. Instead, what Agentmemory allows you to obtain is a semantic external brain.
Keep structured memory outside the session, not inside. Call up only what you need when you need it, and close it when finished. Things worth remembering grow over time, while things that can be forgotten quietly decay. It's the same structure as how humans use memory.
The change that occurs in a developer's mind can be described in one sentence: a transition from "it ends when the session is cut" to "memory grows between sessions."
The entire industry is moving in this direction. DeepLearning.AI's agent memory course, Mem0's message of "making stateless agents stateful," the MemGPT paper "LLMs as Operating Systems"—ultimately, these are all about external memory, and Agentmemory is one solution in the coding agent context.
Whether it's Mem0, Letta, or your own implementation, for those who seriously use Codex / Claude Code, it is currently the fastest tool to try the "sensation of infinite memory." Frankly, it's worth installing.
9. About This Account
To those who have read this far: this account @Codestudiopjbk is run by three hardcore Codex users.
● Participation in development programs for grad students and postdocs
● Won 300,000 yen in prize money
● Currently co-developing AI agents with listed companies
Our usual content includes:
● Implementation examples using GPT-5.5 / OpenAI Codex
● Codex utilization, CLI automation, and development trends
● Translation and verification of the latest overseas GPT-5.5 / Codex info
● Practical comparisons with Claude Code (based on hundreds of hours of use)
● Learnings from joint development with listed companies
We post daily about the entire process of bringing a working product to the world, from development philosophy to design, implementation, and improvement. If you're interested, please follow and check us out. It'll be worth your while.
For development-related consultations, please DM us. Feel free to reach out for Codex introduction, automation design, or AI agent implementation.
References & Citations
● [Rohit Ghumare (rohitg00/agentmemory)] (2026-05-13) Agentmemory v0.9.12 — Memory Engine for Coding Agents — Official repo, Apache-2.0, 8.8k Stars, TypeScript
● [Rohit Ghumare] (2026-04) "Built this 6 months ago with agentmemory: persistent memory for AI coding agents" — Developer philosophy
● [GitHub Issue #181] Stop-hook → /summarize → agent-sdk infinite recursion — Primary source for Pitfall 2
● [GitHub Issue #159] Standalone MCP tools don't proxy to running agentmemory server — Primary source for Pitfall 3
● [Anthropic Engineering] Effective Context Engineering for AI Agents — Official guidance on context engineering
● [Anthropic] (2026-04-23) April 23 Postmortem — Social proof of the Claude Code thinking length collapse incident
● [Mem0] Introducing Mem0 — Mem0 philosophy and Taranjeet Singh citation
● [Letta] Benchmarking AI Agent Memory — Source for Letta benchmark numbers
● [Charles Packer et al.] (2023-10) MemGPT: Towards LLMs as Operating Systems — Virtual context management paper, theoretical predecessor to Agentmemory
● [DeepLearning.AI] Agent Memory: Building Memory-Aware Agents — Andrew Ng / Oracle course
