Agentmemory Architecture
Understand how agentmemory stores, retrieves, and serves agent observations so you can extend or debug your local memory server.
Overview
agentmemory-architecture is an agent skill most often used in Build (also Operate) that explains how agentmemory’s iii-engine functions, hybrid retrieval, storage lifecycle, and ports work end to end.
Install
npx skills add https://github.com/rohitg00/agentmemory --skill agentmemory-architectureWhat is this skill?
- Explains agentmemory as a local memory server on the iii engine (functions, triggers, worker state)
- Hybrid recall: BM25 keyword search, vector similarity, and graph expansion over linked concepts
- Default on-device embeddings—no API key required for baseline retrieval
- REST anchor port 3111 with streams N+1 and viewer N+2; MCP and REST serving
- Lifecycle: capture, compress, consolidate, and forget to avoid unbounded growth
- REST anchor port 3111; streams port N+1; viewer port N+2
- Hybrid recall combines BM25, vector similarity, and graph expansion
Adoption & trust: 3 installs on skills.sh; 21.9k GitHub stars; trending (+300% hot-view momentum).
What problem does it solve?
You are extending or debugging a local agent memory server but do not know how iii primitives, hybrid search, and lifecycle rules fit together.
Who is it for?
Solo builders running agentmemory locally who will modify retrieval, storage, or MCP/REST integration and need architecture context first.
Skip if: Builders who only want high-level “save context” usage with no plan to read ports, BM25/vector/graph behavior, or iii registration patterns.
When should I use this skill?
Reasoning about how agentmemory stores or retrieves memory end to end, extending the system, or answering how it works under the hood.
What do I get? / Deliverables
You and your agent share an accurate end-to-end model so new mem::* functions, triggers, and retrieval tweaks align with how agentmemory is actually built.
- Accurate architectural explanation for agent-driven changes to memory functions, triggers, retrieval, or ports
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Agent memory architecture is foundational while you build agent tooling, even though you revisit it when operating production-like local setups. agent-tooling is the canonical shelf for skills that explain how coding-agent infrastructure works end to end.
Where it fits
Map new mem::* functions and api::* triggers before shipping a custom consolidation worker on iii.
Decide how REST at 3111 and MCP clients should share the same hybrid recall path.
Diagnose why graph expansion returns stale concepts after compress/consolidate runs.
Tune forget lifecycle rules when the local memory store grows faster than expected.
How it compares
Architecture reference for the agentmemory server—not a generic RAG tutorial or a hosted memory SaaS integration skill.
Common Questions / FAQ
Who is agentmemory-architecture for?
Indie developers and agent authors using agentmemory on the iii engine who need to reason about storage, hybrid recall, and HTTP/MCP surfaces before changing code.
When should I use agentmemory-architecture?
In Build agent-tooling when designing extensions; in Operate monitoring/iterate when recall quality or port layout breaks; anytime the agent must explain how memory is stored and retrieved.
Is agentmemory-architecture safe to install?
The skill is descriptive documentation only; still review the Security Audits panel on this Prism page and audit the agentmemory repo you run locally before exposing REST/MCP ports.
SKILL.md
READMESKILL.md - Agentmemory Architecture
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.