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