agentmemory-architecture
rohitg00/agentmemory
Understand agentmemory's architecture: iii engine primitives, hybrid retrieval, storage lifecycle, and ports.
What is agentmemory-architecture?
agentmemory is a local memory server for coding agents built on the iii engine. It captures observations, indexes them via hybrid retrieval (BM25 + vectors + graph), and serves them over REST and MCP. Use this skill to reason about memory storage and retrieval end-to-end, extend the system, or understand how it works under the hood.
- Runs on iii engine primitives: functions, triggers, and worker state with no separate plugin system
- Hybrid retrieval combining BM25 keyword search, vector similarity, and graph expansion over linked concepts
- On-device embeddings by default; optional LLM provider for richer summaries and auto-injection
- Memory lifecycle of capture, compress, consolidate, and forget to prevent unbounded growth
- REST API at port 3111, streams at N+1, viewer at N+2, engine at N+46023 (configurable via --instance flag)
- Real-time web viewer at http://localhost:3113 for monitoring memory capture and session building
How to install agentmemory-architecture
npx skills add https://github.com/rohitg00/agentmemory --skill agentmemory-architecture- agentmemory installed and running locally
- Understanding of iii engine concepts (functions, triggers, worker state)
- Familiarity with REST APIs and MCP protocol
How to use agentmemory-architecture
- 1.Review the iii primitives section to understand how functions and triggers route capability
- 2.Check the ports section to identify which endpoint serves your use case (REST at 3111, streams at 3112, viewer at 3113)
- 3.Access the real-time viewer at http://localhost:3113 to confirm memory capture is working
- 4.For new capabilities, register a function (mem::*) and HTTP trigger (api::*) on the iii engine
- 5.Adjust ports using --instance N if running multiple instances (shifts all ports by N*100)
- 6.Consult agentmemory-mcp-tools, agentmemory-rest-api, agentmemory-hooks, and agentmemory-config for specific surfaces and configuration
Use cases
- Extending agentmemory with new capabilities by adding functions and triggers to the iii engine
- Configuring memory ports and instance offsets for multi-instance deployments
- Debugging memory capture and retrieval by inspecting the real-time viewer
- Understanding how observations flow from capture through indexing to retrieval
- Integrating custom storage or retrieval logic into the memory lifecycle
- Developers extending or customizing agentmemory
- System architects designing multi-agent memory infrastructure
- Engineers debugging memory capture and retrieval issues
- Teams deploying agentmemory across multiple instances
agentmemory-architecture FAQ
Retrieval is hybrid: BM25 keyword search, vector similarity from on-device embeddings, and graph expansion over linked concepts. Optional LLM providers can add richer summaries.
No. The default install runs embeddings on-device and BM25 needs no key. An LLM provider is optional and only adds richer summaries and auto-injection.
Memories carry content, concepts, files, importance, and timestamps, grouped into sessions and optionally linked to commits. A lifecycle of capture, compress, consolidate, and forget prevents unbounded growth.
REST is at 3111, streams at 3112, viewer at 3113, and engine at 49134. Use --instance N to shift all ports by N*100.
Register a new function (mem::*) and HTTP trigger (api::*) on the iii engine. There is no separate plugin system; new capability is a function plus a trigger.
Full instructions (SKILL.md)
Source of truth, from rohitg00/agentmemory.
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 is hybrid: BM25 keyword search plus vector similarity plus graph expansion over linked concepts. The default install needs no API key because embeddings run on-device and BM25 needs none. An LLM provider only adds richer summaries and auto-injection, both opt-in.
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.
Related skills
More from rohitg00/agentmemory and the wider catalog.
agentmemory-config
Configure agentmemory environment variables, ports, API keys, and feature flags.
agentmemory-hooks
Automatic memory capture hooks across agent sessions—zero-LLM observation recording.
agentmemory-mcp-tools
Index of agentmemory MCP tools: which tool to call, exact parameters, and when to use each.
agentmemory-rest-api
HTTP REST API for agentmemory memory server—save and recall agent knowledge over HTTP.
commit-context
Trace code back to the agent session that created it—answer 'why is this here' and 'what was the agent doing'.
commit-history
List recent git commits linked to agent sessions, filtered by branch or repo.