How to use the agentmemory Architecture Guide agent skill

What a skill is and what this one does

An agent skill is a folder of instructions that an AI assistant can load when a task matches the skill's description. This skill is a reference guide. It covers how agentmemory stores memories, how it retrieves them, the ports it uses, and where the local viewer lives.

With the skill installed, the agent can reason about memory end to end, explain why a memory may or may not have been retrieved, and help you think through extending the system. It does not change your files or run commands by itself.

Install the skill from the ZIP or the Claude apps

Option 1: download the ZIP from this page and unzip it into ~/.claude/skills/ to make it available to you across projects, or into a project's .claude/skills/ folder to limit it to that project.

Option 2: in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

The package contains SKILL.md and TROUBLESHOOTING.md. The skill itself requires agentmemory to already be installed, because it describes agentmemory rather than installing it.

• Folder for all projects: ~/.claude/skills/
• Folder for one project: .claude/skills/ inside that project
• Claude apps: Settings → Capabilities → Skills

Trigger the skill with natural requests

The skill is not meant to be invoked by name. Its description tells the agent when to use it, so ask a question about how agentmemory works and the agent can load it. Phrases that match the skill's purpose include asking how memories are stored or retrieved, asking how to extend the system, or asking which ports agentmemory uses.

If the agent answers a general question without the detail you expected, name the topic directly, such as the viewer or the storage model.

• How does agentmemory decide which memories to return when I search?
• Which ports does agentmemory use, and can I change them?
• Where is the local viewer and what does it show?
• How are memories grouped into sessions and linked to commits?
• I want to add a new capability to agentmemory. Where do I start?

Know what the skill explains

The guide describes agentmemory as a local memory server that captures observations, indexes them for hybrid retrieval, and serves them over REST and MCP. It explains that everything is a function, a trigger, or worker state on the iii engine, and that new capability is a new function plus a trigger.

Recall combines BM25 keyword search with configured vector similarity and graph expansion. Without an embedding provider, BM25 works without an API key. Setting EMBEDDING_PROVIDER=local enables on-device embeddings, which may download a model. Memories carry content, concepts, files, importance and timestamps, and move through a lifecycle of capture, compress, consolidate and forget.

For ports, REST defaults to 3111, the viewer to 3113, and the internal engine WebSocket to 49134. You can select another local runtime with --port <N> or --instance <N>. The viewer at http://localhost:3113 shows memory building as sessions run.

• REST API default port: 3111
• Viewer default port: 3113
• Internal engine WebSocket: 49134

Troubleshoot missing tools with the included guide

If an agent says an MCP tool is not available, the bundled TROUBLESHOOTING.md lists the first checks. It advises identifying your host, then restarting or reloading the affected host connection after configuration changes. In Claude Code it points to /plugin list and /mcp.

The guide also warns not to run another host's setup commands, so follow the steps that match your host.