Agent memory is becoming its own category.
After looking at Second Brain Cloudflare, I wanted to compare it with a more local, coding-agent-focused memory layer.
AgentMemory is that kind of project.
It is a persistent memory daemon for coding agents: Claude Code, Codex CLI, Cursor, Gemini CLI, GitHub Copilot CLI, Hermes, OpenClaw, OpenCode, and other MCP clients.
The short version:
AgentMemory = local memory daemon + iii engine + REST + MCP + hooks + viewer
It is not a Cloudflare app. It is not a note-taking PWA. It is closer to a local infrastructure layer that coding agents can share.
What is AgentMemory?
AgentMemory runs a local service that captures observations from agent sessions, compresses them into memories, indexes them, and exposes recall through REST and MCP.
The project claims broad agent support through:
- MCP server integration;
- native plugins and hooks;
- REST API;
- a real-time viewer;
- a CLI;
- optional Docker/managed deployment templates.
The default local runtime uses four ports:
| Port | Purpose |
|---|---|
3111 |
REST API and MCP HTTP anchor |
3112 |
iii stream worker |
3113 |
real-time viewer |
49134 |
iii worker WebSocket |
Those ports can be shifted with --port. For example, --port 3411 moves the quartet to 3411, 3412, 3413, and 49434.
Architecture
AgentMemory is a TypeScript/Node.js package published as @agentmemory/agentmemory.
The architecture has a few important pieces:
| Component | Role |
|---|---|
agentmemory CLI |
Starts/stops the daemon, wires agents, runs diagnostics, launches status/viewer helpers |
| iii engine | Pinned runtime engine used for functions, HTTP triggers, streams, state, queues, cron, and worker registration |
| AgentMemory worker | Registers memory functions and REST/MCP endpoints against iii |
| State store | File-backed by default, Redis optional |
| Search index | BM25 by default; optional vectors when embeddings are enabled |
| Real-time viewer | Browser UI for sessions, memories, graph, lessons, audit, health, and activity |
| MCP shim | @agentmemory/mcp, which proxies to the full server when available |
| Hooks/plugins | Capture activity from supported agents |
The package pins iii-sdk and @iii-dev/helpers to 0.22.1, and the Docker/CLI path expects the matching iii engine version.
That version pin matters. The Worker and engine speak a specific protocol, so bumping one without the other is not the intended path.
Search Model
AgentMemory does not require an embedding key to run.
In keyless mode, it stores and searches memory using BM25-style keyword retrieval. That makes the default path usable without OpenAI, Anthropic, Gemini, Voyage, Cohere, or OpenRouter credentials.
For semantic recall, you can opt into embeddings:
EMBEDDING_PROVIDER=local
Local embeddings use Xenova/all-MiniLM-L6-v2 with 384 dimensions. The first embedding request downloads the model; after that, inference runs locally.
Remote embedding providers are also supported through provider keys.
The recall stack can combine:
- BM25 keyword search;
- optional vector search;
- graph traversal when graph data exists;
- Reciprocal Rank Fusion;
- session diversification;
- optional reranking.
That is a good fit for coding work. Exact strings matter in codebases: file paths, function names, error messages, branch names, issue IDs, and command names often beat pure semantic search.
Field Test
I tested AgentMemory from the cloned source using a temporary home directory and alternate ports, so it did not wire itself into my real Codex or Claude configuration.
Environment:
Node: 24.21.0 for build/test/runtime
AgentMemory: 0.9.30
iii engine: 0.22.1
Mode: zero-LLM / BM25
Ports: 3411 REST, 3412 streams, 3413 viewer, 49434 engine
The source tree has no lockfile, so npm ci is not usable. A normal install worked with Node 24 and npm 11:
HOME=/tmp/agentmemory-home npx -y -p node@24 -p npm@11 -c 'npm install --ignore-scripts'
The build passed:
HOME=/tmp/agentmemory-home npx -y -p node@24 -p npm@11 -c 'npm run build'
The full non-integration test suite mostly passed, but one test timed out:
236 passed files
2593 passed tests
1 failed test: test/capture-spool.test.ts > stops at the byte limit and reports the overflow
I then started the daemon:
HOME=/tmp/agentmemory-home \
CI=1 \
AGENTMEMORY_DATA_DIR=/tmp/agentmemory-data \
npx -y -p node@24 node dist/cli.mjs --port 3411
The server generated a local secret and came up with:
REST API http://localhost:3411
Viewer http://localhost:3413
Streams ws://localhost:3412
Engine ws://localhost:49434
Health worked:
curl http://127.0.0.1:3411/agentmemory/livez
The authenticated health endpoint also returned a healthy worker/engine status:
curl -H "Authorization: Bearer $(cat /tmp/agentmemory-home/.agentmemory/secret)" \
http://127.0.0.1:3411/agentmemory/health
I saved a memory:
curl -X POST http://127.0.0.1:3411/agentmemory/remember \
-H "Authorization: Bearer $(cat /tmp/agentmemory-home/.agentmemory/secret)" \
-H "Content-Type: application/json" \
-d '{"content":"Foss Engineer field test: agentmemory stores persistent coding-agent memory with BM25 search in zero-LLM mode.","concepts":["foss","agentmemory","bm25"],"project":"foss-field-test"}'
And then retrieved it:
curl -X POST http://127.0.0.1:3411/agentmemory/smart-search \
-H "Authorization: Bearer $(cat /tmp/agentmemory-home/.agentmemory/secret)" \
-H "Content-Type: application/json" \
-d '{"query":"persistent coding agent BM25 memory","limit":5}'
The search returned the inserted memory.
The viewer HTML served from:
http://127.0.0.1:3413/agentmemory/viewer
The root path on the shifted viewer port returned JSON 404, so /agentmemory/viewer is the safer URL to document from this field test.
Self-Hosting Paths
For most local users, the canonical path is npm:
npx -y @agentmemory/agentmemory@latest
That starts the local daemon and installs or starts the pinned iii engine.
For a clean, non-interactive validation run, prefer an explicit data dir and port:
AGENTMEMORY_DATA_DIR=/opt/agentmemory-data \
npx -y @agentmemory/agentmemory@latest --port 3111
Day-to-day commands:
agentmemory status
agentmemory doctor
agentmemory stop
agentmemory connect codex
agentmemory connect claude-code
The project also ships deployment templates for Fly.io, Railway, Render, and Coolify. Those templates are more useful when you want a remote memory service reachable by multiple machines.
For a homelab, I would start with the local daemon first. Add Docker only if you specifically want the memory server to behave like another always-on service behind a reverse proxy.
Security Notes
AgentMemory generates a local secret if AGENTMEMORY_SECRET is not set. Local bundled clients can read that secret from the user data directory.
Manual API calls need:
Authorization: Bearer <secret>
Important details:
- the REST API binds to loopback by default;
- the viewer binds to loopback by default;
- remote deployments should use HTTPS;
- the viewer has Host-header protections for non-loopback binds;
- write requests require JSON content type;
- secrets are scrubbed before storage on write paths.
The safe default is local-only. If you expose AgentMemory across the LAN or internet, treat it as sensitive agent memory infrastructure.
How It Compares
| Project | Best Fit |
|---|---|
| Second Brain Cloudflare | Cloudflare-hosted MCP memory with D1, Vectorize, Workers AI, KV, and a PWA dashboard |
| AgentMemory | Local coding-agent memory daemon with hooks, MCP, REST, BM25, optional vectors, and viewer |
| Hermes Agent | The agent runtime itself: model routing, skills, memory, cron, tools, and gateway integrations |
| OpenClaw | Personal assistant gateway/runtime |
The key distinction:
Hermes / OpenClaw = agent runtime
AgentMemory = memory service those agents can use
Second Brain CF = Cloudflare-native memory service
AgentMemory can be complementary to Hermes or OpenClaw. In fact, the repository includes integration notes for Hermes and OpenClaw.
FAQ
Is AgentMemory self-hosted?
Yes.
The default mode is local self-hosting on your own machine. It runs a local daemon, a pinned iii engine, a REST API, MCP endpoints, and a viewer.
There are also Docker/managed deployment templates for remote hosting, but the simplest self-hosted path is still the npm CLI.
Is this a web app or a CLI?
It is both, but the primary object is the daemon.
You start it with the CLI, agents talk to it through MCP/REST/hooks, and humans inspect it through the viewer at port 3113.
The viewer is useful, but this is not a notes app where the browser is the main workflow.
Which ports does AgentMemory use?
By default:
| Port | Purpose |
|---|---|
3111 |
REST API and MCP HTTP |
3112 |
iii streams |
3113 |
real-time viewer |
49134 |
iii engine WebSocket |
Use --port <N> to shift the group. For example, --port 3411 gives 3411, 3412, 3413, and 49434.
How do I open the viewer?
For the default port:
http://localhost:3113/agentmemory/viewer
In my shifted-port test:
http://localhost:3413/agentmemory/viewer
The viewer binds to 127.0.0.1 by default. That is intentional. Exposing it to a LAN or reverse proxy requires explicit viewer host and allowed-host configuration.
Does it need OpenAI, Anthropic, Gemini, or another LLM key?
No for the base memory server.
Keyless mode works with zero-LLM synthetic compression and BM25 search. That is enough for basic persistent memory and exact-ish recall.
LLM provider keys unlock richer compression, summarization, consolidation, reflection, and graph extraction.
Does it use embeddings?
Only when configured.
By default, keyless installs do not use vector embeddings. To use local embeddings, set:
EMBEDDING_PROVIDER=local
That downloads Xenova/all-MiniLM-L6-v2 on first use and then runs inference locally.
Remote embedding providers are also supported.
What is the difference between MCP shim mode and the full server?
The @agentmemory/mcp package is a shim.
When it can reach a running AgentMemory server through AGENTMEMORY_URL, it proxies to the full tool surface. When it cannot reach the daemon, it falls back to a smaller local in-memory MCP set.
So if your MCP client only shows a small number of tools, check that the daemon is running and that AGENTMEMORY_URL points to it.
How is AgentMemory different from Second Brain Cloudflare?
Second Brain Cloudflare is a Cloudflare-native memory service. It uses Workers, D1, Vectorize, Workers AI, KV, and a browser dashboard/PWA.
AgentMemory is local-first. It runs a daemon and iii engine on your machine or server, captures coding-agent events through hooks, and can work without any cloud database or LLM key.
Pick Second Brain Cloudflare if you want Cloudflare-managed infrastructure and Workers AI embeddings. Pick AgentMemory if you want a local coding-agent memory daemon with broad plugin/hook coverage.
How should I think about AgentMemory vs Hermes vs Second Brain?
AgentMemory is closer to Second Brain Cloudflare than to Hermes, but the deployment model is different.
The clean mental model is:
| Tool | What it mainly is |
|---|---|
| AgentMemory | Local memory daemon for coding agents |
| Second Brain Cloudflare | Cloudflare-hosted memory service for AI/MCP tools |
| Hermes Agent | Full agent runtime that can use memory |
Or shorter:
Hermes = the agent
AgentMemory = local memory backend for agents
Second Brain = Cloudflare memory backend for agents/tools
Hermes runs the assistant loop, tools, skills, cron, model routing, and gateway integrations. AgentMemory does not try to be that full runtime. It gives agents durable memory through REST, MCP, hooks, and plugins.
That means they can be complementary: Hermes can use AgentMemory as a memory backend, and the AgentMemory repo includes Hermes integration notes.
How is AgentMemory different from Hermes Agent?
Hermes Agent is an agent runtime. It runs the assistant loop, model/tool execution, scheduled work, skills, and gateway integrations.
AgentMemory is not the agent. It is the memory service the agent can use.
The clean mental model:
Hermes Agent = the worker
AgentMemory = the memory backend
They can be used together. The AgentMemory repository includes Hermes integration notes, including MCP wiring and deeper plugin hooks.
Does AgentMemory rely only on local Markdown files?
No.
AgentMemory is not just a folder of .md files. It runs a daemon backed by the iii engine and stores structured persistent state: sessions, observations, compressed observations, memories, graph data, audit logs, indexes, streams, and runtime metadata.
Native default data locations are:
| OS | Default data location |
|---|---|
| Linux | $XDG_DATA_HOME/agentmemory or ~/.local/share/agentmemory |
| macOS | ~/Library/Application Support/agentmemory |
| Windows | %APPDATA%\\agentmemory |
You can override the location with:
AGENTMEMORY_DATA_DIR=/path/to/agentmemory-data
It can integrate with Markdown-like workflows and export/import data, but Markdown files are not the core storage model.
Are embeddings required?
No.
The default keyless mode is:
BM25 keyword search
zero-LLM synthetic compression
no vector embeddings
That means AgentMemory can run without OpenAI, Anthropic, Gemini, Voyage, Cohere, OpenRouter, or another model provider.
To enable local embeddings, set:
EMBEDDING_PROVIDER=local
That uses:
Xenova/all-MiniLM-L6-v2
384 dimensions
local inference after the first model download
Remote embedding providers are also supported. The practical difference is that BM25 is good for exact coding artifacts like file paths, function names, error strings, and command names, while embeddings help with meaning-based recall.
Can I run it with Docker?
Yes, but I did not validate the full Docker deployment path during this pass.
The repository includes Docker-oriented templates for managed deployment targets such as Coolify, Fly.io, Railway, and Render. The Coolify path builds an image with Node, the pinned iii binary, the npm AgentMemory package, a /data volume, and a first-boot secret.
For a personal workstation or homelab, I would test the npm daemon first. Use Docker when you want process isolation, a persistent /data volume, and reverse-proxy routing.
What did the local field test prove?
It proved the source build works, the daemon starts with a temp data dir, the REST API becomes healthy, a memory can be saved with bearer auth, BM25-based smart-search can retrieve it in zero-LLM mode, and the viewer HTML serves under /agentmemory/viewer.
It also showed two caveats:
- no lockfile, so
npm ciis not available; - the broad Vitest suite had one timeout in
test/capture-spool.test.tson this machine.
Where does the data live?
Native runs use a platform data directory by default:
| OS | Default data location |
|---|---|
| macOS | ~/Library/Application Support/agentmemory |
| Linux | $XDG_DATA_HOME/agentmemory or ~/.local/share/agentmemory |
| Windows | %APPDATA%\\agentmemory |
You can override it with:
AGENTMEMORY_DATA_DIR=/path/to/agentmemory-data
Back up that directory if you care about the memories.
Comments