agentmemory-architecture — Claude Code skill: how agent memory works
A skill that walks through the agentmemory server: the iii engine, storage model, ports and viewer. Useful when you extend it or debug recall.
npx skills add rohitg00/agentmemory --skill agentmemory-architecture -a claude-codeWhat agentmemory-architecture does
agentmemory is a memory server for coding agents. It runs locally, captures observations, indexes them for hybrid retrieval and serves them back over REST and MCP. This skill documents how that is put together on the iii engine.
There is no separate plugin system. Everything is a function, a trigger or worker state: the worker registers mem::* functions and api::* HTTP triggers, and the engine routes the calls. Adding a capability means adding a function plus a trigger.
Recall mixes BM25 keyword search with vector similarity and graph expansion. A clean install with no embedding provider runs BM25 and needs no API key. EMBEDDING_PROVIDER=local turns on on-device embeddings, which may download a model; LLM compression and summaries need a configured provider. Memories carry content, concepts, files, importance and timestamps, grouped into sessions and optionally linked to commits, and move through capture, compress, consolidate and forget. REST sits on 3111, streams on 3112, the viewer on 3113, the engine on 49134, and --instance N shifts the block by N*100. The viewer at http://localhost:3113 shows memory building as sessions run.
What it helps with
- trace how memory is stored and retrieved end to end
- extend agentmemory with a new function and trigger
- pick a retrieval mode that works without an API key
- shift the port block for a second instance
- confirm that capture is actually running
Example prompts for the agent
- Explain how agentmemory stores and retrieves memory end to end
- How do I add a new
mem::*function andapi::*trigger to agentmemory? - Why is the viewer at
http://localhost:3113showing nothing?
How to install agentmemory-architecture
1Skills CLI (Vercel)
npx skills add rohitg00/agentmemory --skill agentmemory-architecture -a claude-code2Manually: put the files in place
~/.claude/skills/agentmemory-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/agentmemory-architecture/
1Skills CLI (Vercel)
npx skills add rohitg00/agentmemory --skill agentmemory-architecture -a codex2Manually: put the files in place
.agents/skills/agentmemory-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rohitg00/agentmemory --skill agentmemory-architecture -a cursor2Manually: put the files in place
.cursor/skills/agentmemory-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rohitg00/agentmemory agentmemory-architecture2Manually: put the files in place
.github/skills/agentmemory-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add rohitg00/agentmemory --skill agentmemory-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/rohitg00/agentmemory --path plugin/skills/agentmemory-architectureManually: put the files in place
.devin/skills/agentmemory-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add rohitg00/agentmemory --skill agentmemory-architecture -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about agentmemory-architecture
How do I install agentmemory-architecture in Claude Code?
Run npx skills add rohitg00/agentmemory --skill agentmemory-architecture -a claude-code. The skill lands at ~/.claude/skills/agentmemory-architecture/SKILL.md.
What does agentmemory-architecture do?
It documents the agentmemory server: the iii engine primitives, the retrieval model, storage and lifecycle, ports and the web viewer.
Do I need an API key for memory search?
Not unless you configure an embedding provider — a clean install searches with BM25 and no key. On-device embeddings come from EMBEDDING_PROVIDER=local, and LLM compression and summaries require a configured provider.
Source text
SKILL.md · Apache-2.0
--- name: agentmemory-architecture description: How agentmemory is built, the iii engine primitives it runs on, its storage model, ports, and the viewer. Use when reasoning about how memory is stored or retrieved end to end, when extending the system, or when answering how agentmemory works under the hood. user-invocable: false --- agentmemory is a memory server for coding agents. It runs locally, captures observations, indexes them for hybrid retrieval, and serves them back over REST and MCP. It is built on the iii engine. ## iii primitives Everything is a function, a trigger, or worker state on the iii engine. There is no separate plugin system; the worker registers functions (`mem::*`) and HTTP triggers (`api::*`) and the engine routes calls. agentmemory does not bypass iii; new capability is a new function plus a trigger. ## Retrieval model Recall combines BM25 keyword search with configured vector similarity and graph expansion. A clean installation without an embedding provider uses BM25 without an API key. Set `EMBEDDING_PROVIDER=local` to enable on-device embeddings, which may download a model, or configure a remote provider. LLM compression and summaries require a configured provider and their relevant options. ## Storage and lifecycle Memories carry content, concepts, files, importance, and timestamps, grouped into sessions and optionally linked to commits. A lifecycle of capture, compress, consolidate, and forget keeps the store useful over time rather than letting it grow unbounded. ## Ports REST is the anchor at 3111. Streams = N+1 (3112), viewer = N+2 (3113), engine = N+46023 (49134). `--instance N` shifts the whole block by N*100. ## Viewer A real-time web viewer at `http://localhost:3113` shows memory building as sessions run. Useful for demos and for confirming capture is working. ## See also - agentmemory-mcp-tools and agentmemory-rest-api for the surfaces. - agentmemory-hooks for automatic capture. - agentmemory-config for ports and feature flags.
© rohitg00 · Apache-2.0 · rohitg00/agentmemory
