1. Project Overview & Quickstart (rohitg00/agentmemory) Copy Chapter

File: README.md Copy Chapter

Install Copy Chapter

One command:

npx @agentmemory/agentmemory

The first run is an interactive setup: pick the agents to wire (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), pick an LLM provider or stay keyless, and it seeds the config, starts the memory server on :3111, and offers to install globally so the bare agentmemory command works everywhere afterwards.

Then prove recall works and give your agent its skills:

agentmemory demo --serve                 # seed sample sessions + watch recall find them
npx skills add rohitg00/agentmemory -y   # 17 native skills so your agent knows when to reach for memory

Prefer to let a coding agent do the whole thing? Hand it one instruction:

Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md

Wire more agents any time with agentmemory connect <agent> — 20 adapters listed at Works with every agent. Full command reference at Quick Start.

Windows

The fast path is WSL2. Native Windows engine setup is manual (about 10 to 20 minutes) and agentmemory connect is currently unsupported there. See the Windows notes for the step-by-step.

Global install / EACCES

npm install @agentmemory/agentmemory
# If you hit EACCES on macOS/Linux system Node installs:
sudo npm install @agentmemory/agentmemory

npx serves an old version

npx caches per version. Force the latest with npx -y @agentmemory/agentmemory@latest, or clear the cache once with rm -rf ~/.npm/_npx (macOS/Linux; on Windows delete %LOCALAPPDATA%\npm-cache\_npx).

Already running your own iii engine

agentmemory pins iii-engine v0.11.2 and won't attach to a different version (the worker can't speak another engine's protocol). Stop the other engine, then run npx -y @agentmemory/agentmemory@latest. It installs and runs the pinned v0.11.2 in ~/.agentmemory/bin, leaving your own iii untouched.

agentmemory works with any agent that supports hooks, MCP, or REST API. All agents share the same memory server.

|
Claude Code
native plugin + 12 hooks + MCP |
Codex CLI
native plugin + 6 hooks + MCP |
GitHub Copilot CLI
MCP + plugin hooks/skills |
OpenClaw
native plugin + MCP |
Hermes
native plugin + MCP |
pi
native plugin + MCP |
OpenHuman
native Memory trait backend |
Cursor
native plugin + MCP |
Gemini CLI

MCP server |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
OpenCode
22 hooks + MCP + plugin |
Cline
MCP server |
Goose
MCP server |
Kilo Code
MCP server |
Aider
REST API |
Claude Desktop
MCP server |
Devin
6 hooks + MCP |
Roo Code
MCP server | |
|
Warp
connect + MCP + skills | | | | | | | | |

You explain the same architecture every session. You re-discover the same bugs. You re-teach the same preferences. Built-in memory (CLAUDE.md, .cursorrules) caps out at 200 lines and goes stale. agentmemory fixes this. It silently captures what your agent does, compresses it into searchable memory, and injects the right context when the next session starts. One command. Works across agents.

What changes: Session 1 you set up JWT auth. Session 2 you ask for rate limiting. The agent already knows your auth uses jose middleware in src/middleware/auth.ts, your tests cover token validation, and you chose jose over jsonwebtoken for Edge compatibility, with no re-explaining and no copy-pasting.

npx @agentmemory/agentmemory

By default, agentmemory stores iii-engine state outside the repository you start it from: ~/Library/Application Support/agentmemory on macOS, $XDG_DATA_HOME/agentmemory or ~/.local/share/agentmemory on Linux, and %APPDATA%\agentmemory on Windows. To choose a location, pass --data-dir or set AGENTMEMORY_DATA_DIR:

npx @agentmemory/agentmemory --data-dir ~/.agentmemory-projects/main
AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx @agentmemory/agentmemory

Latest release notes: CHANGELOG.md.

| ### Retrieval Accuracy

coding-agent-life-v1 (in-house corpus, sandbox-reproducible)

Adapter P@5 R@5 Top-5 hit rate p50 latency

agentmemory hybrid 0.240 1.000 15 / 15 14 ms
grep baseline 0.227 0.967 15 / 15 0 ms

100% top-5 hit rate at the P@5 math ceiling for this corpus (0.240, see scorecard). Hybrid retrieves every gold session; grep misses 1 of 2 gold on the multi-session temporal query. Lift is recall + temporal, not aggregate precision. This benchmark is small and gold-sparse; the larger LongMemEval-S below differentiates better. Full per-type breakdown + correction note: docs/benchmarks/2026-05-20-coding-agent-life-v1.md.

LongMemEval-S (ICLR 2025, 500 questions)

System R@5 R@10 MRR

agentmemory 95.2% 98.6% 88.2%
BM25-only fallback 86.2% 94.6% 71.5% | ### Token Savings

Approach Tokens/yr Cost/yr

Paste full context 19.5M+ Impossible (exceeds window)
LLM-summarized ~650K ~$500
agentmemory ~170K ~$10

agentmemory + local embeddings ~170K $0 |
| --- | --- |

Embedding model: all-MiniLM-L6-v2 (local, free, no API key). Full reports: benchmark/LONGMEMEVAL.md, benchmark/QUALITY.md, benchmark/SCALE.md. Competitor comparison: benchmark/COMPARISON.md covering agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.

Reproduce locally: eval/README.md, an adapter-pluggable harness for LongMemEval _s (public 500-Q) + coding-agent-life-v1 (in-house 15-session corpus). Grep / vector / agentmemory adapters score side-by-side, NDJSON output, published scorecards land in docs/benchmarks/.

Pairs with codegraph, Understand Anything, and Graphify. Code-graph indexing, multi-agent build pipelines, and broader knowledge graphs across docs / PDFs / images / videos. agentmemory remembers the work; those three projects light up the rest of the context layer. Recipes + question-routing table: docs/recipes/pairings.md.

_{Benchmark note: only agentmemory's R@5 is our own measured result (LongMemEval-S, reproducible from benchmark/COMPARISON.md). The mem0 and Letta figures are their published LoCoMo numbers (a different dataset); the MemPalace, supermemory, TencentDB (PersonaMem), and oracleagentmemory figures are vendor self-reported claims we have not independently reproduced (oracleagentmemory's run used GPT-5.5 against an Oracle AI Database). Shown side by side for ballpark only, not a head-to-head on identical data. Star counts are approximate and drift over time.}

Newer entrants worth knowing, compared in depth in benchmark/COMPARISON.md:

None of these auto-capture from coding-agent hooks, ship a local-first viewer, or run keyless — the combination agentmemory is built around.

Compatibility: this release targets stable iii-sdk ^0.11.0 and iii-engine v0.11.x.

Try it in 30 seconds Copy Section

# Terminal 1: start the server
npx @agentmemory/agentmemory

# Terminal 2: seed sample data and see recall in action
npx @agentmemory/agentmemory demo

demo seeds 3 realistic sessions (JWT auth, N+1 query fix, rate limiting) and runs semantic searches against them. You'll see it find "N+1 query fix" when you search "database performance optimization", which keyword matching cannot do.

Open http://localhost:3113 to watch the memory build live.

Everyday commands Copy Section

Install and setup live in Install above (the first run walks you through it). Day to day:

agentmemory                    # start the server
agentmemory stop               # tear it down
agentmemory connect <agent>    # wire another agent
agentmemory doctor             # interactive diagnostics + fix prompts
agentmemory remove             # uninstall everything we created

Session Replay Copy Section

Every session agentmemory records is replayable. Open the viewer, pick the Replay tab, and scrub through the timeline: prompts, tool calls, tool results, and responses render as discrete events with play/pause, speed control (0.5x to 4x), and keyboard shortcuts (space to toggle, arrows to step).

To bring in older Claude Code JSONL transcripts:

# Import everything under the default ~/.claude/projects
npx @agentmemory/agentmemory import-jsonl

# Or import a single file
npx @agentmemory/agentmemory import-jsonl ~/.claude/projects/-my-project/abc123.jsonl

Imported sessions show up in the Replay picker alongside native ones. Under the hood each entry routes through the mem::replay::load, mem::replay::sessions, and mem::replay::import-jsonl iii functions, with no side-channel servers. Each imported transcript is indexed for search, stamped with origin channel import, and mined for a session crystal and lessons.

Heads-up if you rely on import-jsonl as your primary capture path: Claude Code's cleanupPeriodDays (in ~/.claude/settings.json, default 30) auto-deletes JSONL transcripts older than that window from ~/.claude/projects/. If you install agentmemory fresh on a months-old Claude Code history, anything older than 30 days is already gone before the first import. Either run import-jsonl on a cron, raise cleanupPeriodDays to something higher, or wire the auto-capture hooks (the default plugin install path) so each turn lands in agentmemory while the session is live and the JSONL cleanup stops mattering.

Upgrade / Maintenance Copy Section

Use the maintenance command when you intentionally want to update your local runtime:

npx @agentmemory/agentmemory upgrade

Warning: this command mutates the current workspace/runtime. It can update JavaScript dependencies and pull the pinned iiidev/iii:0.11.2 Docker image. It never installs an unpinned or newer iii engine.

Implementation details live in src/cli.ts (see runUpgrade around the src/cli.ts:544-595 region).

Claude Code (one block, paste it) Copy Section

Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.

Claude Code without the plugin install (MCP-standalone path)

If you wire agentmemory's MCP server through ~/.claude.json directly instead of using /plugin install, Claude Code never resolves ${CLAUDE_PLUGIN_ROOT} and you have to point hook scripts at absolute paths in ~/.claude/settings.json. Those paths typically embed the agentmemory version (e.g. ~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…), so the next upgrade silently breaks every hook.

Workaround:

agentmemory connect claude-code --with-hooks

This merges the same hook commands into ~/.claude/settings.json with absolute paths resolved to the bundled plugin/ directory of the currently installed @agentmemory/agentmemory package. Re-run the command after upgrading agentmemory to refresh the paths. User entries in the same file are preserved; only previous agentmemory entries are replaced. Using the /plugin install path remains the recommended approach.
For remote or protected deployments, launch Claude Code with AGENTMEMORY_URL and AGENTMEMORY_SECRET set. The plugin passes both values through to its bundled MCP server; when AGENTMEMORY_URL is empty, the MCP shim uses http://localhost:3111.

Codex CLI (Codex plugin platform) Copy Section

# 1. start the memory server in a separate terminal
npx @agentmemory/agentmemory

# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory

The Codex plugin ships from the same plugin/ directory as the Claude Code plugin. It registers:

• @agentmemory/mcp as an MCP server (proxies all 54 tools when AGENTMEMORY_URL points at a running agentmemory server; falls back to 7 tools locally when no server is reachable)
• 6 lifecycle hooks: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop
• 9 invocable skills: /recall, /remember, /session-history, /forget, /recap, /handoff, /lesson, /commit-context, /commit-history, plus 8 reference skills the agent loads on demand (memory discipline, MCP tools, REST API, config, agents, hooks, architecture, and the skill-authoring guide)

Codex's hook engine injects CLAUDE_PLUGIN_ROOT into hook subprocesses (per codex-rs/hooks/src/engine/discovery.rs), so the same hook scripts work across both hosts without duplication. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events are Claude-Code-only and are not registered for Codex.

Codex Desktop: plugin hooks currently silent (workaround available)

CodexHooks and PluginHooks are both stable + default-enabled in codex-rs/features/src/lib.rs, but Codex Desktop builds currently do not dispatch plugin-local hooks.json (openai/codex#16430). MCP tools still work; only the lifecycle observations are missing.

Until upstream lands the fix, mirror the same hook commands into the global ~/.codex/hooks.json:

agentmemory connect codex --with-hooks

This adds an idempotent block to ~/.codex/hooks.json referencing absolute paths to the bundled scripts (no ${CLAUDE_PLUGIN_ROOT} expansion needed at user-scope). Re-run the same command after upgrading agentmemory to refresh paths. User entries in the same file are preserved; only previous agentmemory entries are replaced.

GitHub Copilot CLI Copy Section

# MCP-only wiring
agentmemory connect copilot-cli

# Full hooks/skills plugin from the GitHub subdir
copilot plugin install rohitg00/agentmemory:plugin

agentmemory connect copilot-cli merges mcpServers.agentmemory into ~/.copilot/mcp-config.json (or $COPILOT_HOME/mcp-config.json when COPILOT_HOME is set) and preserves existing servers. This adapter is Windows-safe even though other connect adapters still require manual Windows setup. Copilot picks up the MCP server on next launch or after /mcp. Install the plugin as well when you want the full hook/skill experience.

OpenClaw (paste this prompt)

Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.

Full guide: integrations/openclaw/

Hermes Agent (paste this prompt)

Install agentmemory for Hermes. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:

mcp_servers:
  agentmemory:
    command: npx
    args: ["-y", "@agentmemory/mcp"]

memory:
  provider: agentmemory

Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.

Full guide: integrations/hermes/

Other agents Copy Section

Start the memory server: npx @agentmemory/agentmemory

Native skills via `npx skills add` (50+ agents)

agentmemory ships 17 skills in the Claude-Code-style <dir>/SKILL.md format: 9 invocable action skills (remember, recall, recap, handoff, forget, lesson, commit-context, commit-history, session-history) and 8 reference skills the agent loads on demand (memory-discipline, agentmemory-mcp-tools, agentmemory-rest-api, agentmemory-config, agentmemory-agents, agentmemory-hooks, agentmemory-architecture, write-agentmemory-skill). The reference skills carry data tables generated from source, so they never drift. The skills CLI by vercel-labs auto-installs them into the calling agent's native skill directory across 50+ agents (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, and more):

npx skills add rohitg00/agentmemory -y          # auto-detects the calling agent
npx skills add rohitg00/agentmemory -y -a warp  # explicit agent
npx skills add rohitg00/agentmemory -y -a '*'   # install to every installed agent

This is complementary to agentmemory connect <agent>:

• agentmemory connect <agent> writes the MCP server config so the tools are available.
• npx skills add rohitg00/agentmemory installs the skills so the agent knows when to call them.

For the few agents the skills CLI doesn't cover yet (Zed v1.3.x and below), drop the 17 SKILL.md files under the agent's native skill directory yourself; the same format works everywhere.

Standard MCP block

The agentmemory entry is the same MCP server block across every host that uses the mcpServers shape (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):

"agentmemory": {
  "command": "npx",
  "args": ["-y", "@agentmemory/mcp"],
  "env": {
    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
  }
}

Merge this entry into the existing mcpServers object in the host's config file; don't replace the file. If the file already has other servers, add agentmemory next to them as another key inside mcpServers. If mcpServers is missing entirely, paste the block inside { "mcpServers": { ... } }. The ${VAR} placeholders inherit AGENTMEMORY_URL / AGENTMEMORY_SECRET from the shell at MCP-server launch; unset vars pass empty strings and the shim falls back to http://localhost:3111. One wired entry covers both local and remote (k8s / reverse-proxied) deployments.

Sandboxed MCP clients (Flatpak / Snap / restrictive containers) that can't reach the host's localhost: also set "AGENTMEMORY_FORCE_PROXY": "1" in the env block, and point AGENTMEMORY_URL at a route the sandbox can actually reach (e.g. your LAN IP).

Programmatic access (Python / Rust / Node) Copy Section

agentmemory registers its core operations as iii functions (mem::remember, mem::observe, mem::context, mem::smart-search, mem::forget). Any language with an iii SDK can call them directly over ws://localhost:49134, with no separate REST client per language.

pip install iii-sdk         # Python
cargo add iii-sdk           # Rust
npm  install iii-sdk        # Node

from iii import register_worker

iii = register_worker("ws://localhost:49134")
iii.connect()

iii.trigger({
    "function_id": "mem::smart-search",
    "payload": {"project": "demo", "query": "how do tokens refresh"},
})

Worked example: examples/python/ (quickstart + observation/recall flow). REST on :3111 remains available for hosts without an iii runtime.

From source Copy Section

git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start

This starts agentmemory with a local iii-engine if iii is already installed, or falls back to Docker Compose if Docker is available. REST, streams, and the viewer bind to 127.0.0.1 by default.

Install iii-engine manually. agentmemory currently pins iii-engine to v0.11.2. v0.11.6 introduces a new sandbox-everything-via-iii worker add model that agentmemory hasn't been refactored for yet. Pin lifts once the refactor lands. Override with AGENTMEMORY_III_VERSION=<version> if you've migrated to the sandbox model manually.

• macOS arm64: mkdir -p ~/.local/bin && curl -fsSL https://github.com/iii-hq/iii/releases/download/iii/v0.11.2/iii-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin && chmod +x ~/.local/bin/iii
• macOS x64: swap aarch64-apple-darwin for x86_64-apple-darwin
• Linux x64: swap for x86_64-unknown-linux-gnu
• Linux arm64: swap for aarch64-unknown-linux-gnu
• Windows: download iii-x86_64-pc-windows-msvc.zip from iii-hq/iii releases v0.11.2, extract iii.exe, add to PATH

Or use Docker (the bundled docker-compose.yml pulls iiidev/iii:0.11.2). Full docs: iii.dev/docs.

Windows Copy Section

agentmemory runs on Windows 10/11, but the Node.js package alone isn't enough; you also need the iii-engine runtime (a separate native binary) as a background process. The official upstream installer is a sh script and there is no PowerShell installer or scoop/winget package today, so Windows users have two paths:

Option A: prebuilt Windows binary (recommended)

# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 in your browser
#    (we pin to v0.11.2 until agentmemory refactors for the new sandbox
#     model that engine v0.11.6+ requires)
# 2. Download iii-x86_64-pc-windows-msvc.zip
#    (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
# 3. Extract iii.exe somewhere on PATH, or place it at:
#    %USERPROFILE%\.local\bin\iii.exe
#    (agentmemory checks that location automatically)
# 4. Verify:
iii --version
# Should print: 0.11.2

# 5. Then run agentmemory as usual:
npx -y @agentmemory/agentmemory

Option B: Docker Desktop

# 1. Install Docker Desktop for Windows
# 2. Start Docker Desktop and make sure the engine is running
# 3. Run agentmemory — it will auto-start the bundled compose file:
npx -y @agentmemory/agentmemory

Option C: standalone MCP only (no engine). If you only need the MCP tools for your agent and don't need the REST API, viewer, or cron jobs, skip the engine entirely:

npx -y @agentmemory/agentmemory mcp
# or via the shim package:
npx -y @agentmemory/mcp

Diagnostics for Windows: if npx @agentmemory/agentmemory fails, re-run with --verbose to see the actual engine stderr. Common failure modes:

Note: the iii engine is a prebuilt binary, not a cargo crate, so don't try to cargo install it. (The iii SDKs are published on crates.io, npm, and PyPI, but agentmemory doesn't need them.) Supported engine install methods, all pinned to v0.11.2: the prebuilt v0.11.2 binary above, the upstream sh install script with the version pin curl -fsSL https://install.iii.dev/iii/main/install.sh | VERSION=0.11.2 sh (macOS/Linux), and the Docker image iiidev/iii:0.11.2. A bare install.sh | sh installs the latest engine, which agentmemory does not support; always pass VERSION=0.11.2. Easiest of all: just run npx @agentmemory/agentmemory, which fetches the pinned engine into ~/.agentmemory/bin for you.

Deploy

One-click templates for managed hosts. Each one ships a self-contained
Dockerfile that pulls @agentmemory/agentmemory from npm and copies
the iii engine binary in from the official iiidev/iii Docker Hub
image; no pre-built agentmemory image required. Persistent storage
mounts at /data; the first-boot entrypoint overwrites the
npm-bundled iii config (which binds 127.0.0.1) with a deploy-tuned
one that binds 0.0.0.0 and uses absolute /data paths, generates
the HMAC secret, then drops privileges from root to node via
gosu before exec'ing the agentmemory CLI.

Render's one-click deploy button requires render.yaml at the repository root, which we deliberately keep clean. Use the Render Blueprint flow documented in deploy/render/ to point at the in-repo blueprint manually.

Full setup details (HMAC capture, viewer SSH tunnel, rotation, backup,
cost floors) live in deploy/:

• deploy/fly: single machine with
  auto_stop_machines = "stop"; cheapest idle.
• deploy/railway: Hobby plan flat fee,
  volume in the dashboard.
• deploy/render: Blueprint flow,
  automatic disk snapshots on paid plans.
• deploy/coolify: self-hosted on your
  own VPS via Coolify; same Docker
  Compose stack, you own the host and the data.

Only port 3111 is published. The viewer on 3113 stays bound to
loopback inside the container; every template's README documents the
SSH-tunnel pattern for reaching it.

Every coding agent forgets everything when the session ends, and each new session starts with you re-explaining your stack. agentmemory runs in the background and removes that step.

Session 1: "Add auth to the API"
  Agent writes code, runs tests, fixes bugs
  agentmemory silently captures every tool use
  Session ends -> observations compressed into structured memory

Session 2: "Now add rate limiting"
  Agent already knows:
    - Auth uses JWT middleware in src/middleware/auth.ts
    - Tests in test/auth.test.ts cover token validation
    - You chose jose over jsonwebtoken for Edge compatibility
  Zero re-explaining. Starts working immediately.

vs built-in agent memory Copy Section

Every AI coding agent ships with built-in memory: Claude Code has MEMORY.md, Cursor has notepads, Cline has memory bank. These work like sticky notes. agentmemory is the searchable database behind the sticky notes.

Memory Pipeline Copy Section

PostToolUse hook fires
  -> SHA-256 dedup (5min window)
  -> Privacy filter (strip secrets, API keys)
  -> Store raw observation
  -> LLM compress -> structured facts + concepts + narrative
  -> Vector embedding (6 providers + local)
  -> Index in BM25 + vector

Stop / SessionEnd hook fires
  -> Summarize session
  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
  -> Slot reflection (if SLOT_REFLECT_ENABLED=true)

SessionStart hook fires
  -> Load project profile (top concepts, files, patterns)
  -> Hybrid search (BM25 + vector + graph)
  -> Token budget (default: 2000 tokens)
  -> Inject into conversation

4-Tier Memory Consolidation Copy Section

Modeled on how human brains process memory, including sleep consolidation.

Memories decay over time (Ebbinghaus curve). Frequently accessed memories strengthen. Stale memories auto-evict. Contradictions are detected and resolved.

What Gets Captured Copy Section

Key Capabilities Copy Section

Triple-stream retrieval combining three signals:

Fused with Reciprocal Rank Fusion (RRF, k=60) and session-diversified (max 3 results per session).

Hybrid ranking applies to the primary recall path, not just smart-search: mem::search (behind memory_recall) ranks through the same BM25 + vector + graph fusion once the vector index is populated. Lesson recall runs on a dedicated in-memory BM25 index instead of scanning the whole corpus per query. Superseded memory versions are excluded from every recall path; the version chain keeps their history.

BM25 tokenizes Greek, Cyrillic, Hebrew, Arabic, and accented Latin out of the box. For Chinese / Japanese / Korean memories, install the optional segmenters (npm install @node-rs/jieba tiny-segmenter) to split CJK runs into word-level tokens; without them, agentmemory soft-falls to whole-run tokenization and prints a one-time hint on stderr.

Embedding providers Copy Section

agentmemory auto-detects your provider. For best results, install local embeddings (free):

npm install @huggingface/transformers

54 tools, 6 resources, 3 prompts, and 17 skills.

MCP shim vs full server: the published @agentmemory/mcp package is a thin shim. It exposes the full 54-tool surface only when it can reach a running agentmemory server via AGENTMEMORY_URL (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (memory_save, memory_recall, memory_smart_search, memory_sessions, memory_export, memory_audit, memory_governance_delete). The AGENTMEMORY_TOOLS=core|all env var is a server-side flag; setting it in the shim's env block has no effect. If you see only 7 tools in Cursor / OpenCode / Gemini CLI, start npx @agentmemory/agentmemory (or the Docker stack) and set AGENTMEMORY_URL=http://localhost:3111.

54 Tools Copy Section

Three tool surfaces, smallest to largest: AGENTMEMORY_TOOLS=core trims visibility to 8 essentials (memory_save, memory_recall, memory_consolidate, memory_smart_search, memory_sessions, memory_diagnose, memory_lesson_save, memory_reflect); the base set below is the registry's 14 foundational tools; the default (AGENTMEMORY_TOOLS=all) exposes all 54.

Base tools (14)

Extended tools (54 total, the default surface)

6 Resources · 3 Prompts · 17 Skills Copy Section

The table shows the four core skills. The full set is 9 invocable skills plus 8 reference skills; see the Native skills section above.

Standalone MCP Copy Section

Run without the full server, for any MCP client. Either of these works:

npx -y @agentmemory/agentmemory mcp   # canonical (always available)
npx -y @agentmemory/mcp                # shim package alias

Or add to your agent's MCP config:

Most agents (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

Merge the agentmemory entry into your host's existing mcpServers object rather than replacing the file. For sandboxed clients that can't reach the host's localhost, add "AGENTMEMORY_FORCE_PROXY": "1" to the env block and set AGENTMEMORY_URL to a route the sandbox can reach.

OpenCode (opencode.json):

{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "enabled": true
    }
  },
  "plugin": ["./plugins/agentmemory-capture.ts"]
}

Copy the plugin file from the repo:

mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/

Auto-starts on port 3113. Live observation stream with a stream status indicator, a two-pane session explorer (list beside a sticky detail panel on wide screens), memory and lesson rows that expand to the full stored record including raw JSON and origin provenance, a knowledge graph that clusters nodes by type while relations are sparse, session replay, and a health dashboard.

open http://localhost:3113

The viewer server binds to 127.0.0.1 by default. The REST-served /agentmemory/viewer endpoint follows the normal AGENTMEMORY_SECRET bearer-token rules. CSP headers use a per-response script nonce and disable inline handler attributes (script-src-attr 'none').

The viewer at :3113 shows what your agent remembered. The iii console shows what your agent did: every memory op as an OpenTelemetry trace, every KV entry editable, every function invocable, every stream tappable. Two windows on the same memory: one product-shaped, one engine-shaped.

Watch a memory_smart_search fire and see the BM25 scan → embedding lookup → RRF fusion → reranker as a waterfall. Edit a stuck consolidation timer in the KV browser. Replay a PostToolUse hook with a tweaked payload. Pin the WebSocket stream and watch observations land live.

agentmemory ships this for free because every function call and trigger fires through iii; nothing custom, nothing to instrument.

Already installed. The console ships with iii; no separate installer.

Launch alongside agentmemory:

# agentmemory viewer holds port 3113, so run the console on 3114.
# Engine REST (3111), WebSocket (3112), and bridge (49134) defaults match agentmemory.
iii console --port 3114

Then open http://localhost:3114. Add --enable-flow for the experimental architecture-graph page.

Override engine endpoints only if you've moved them:

iii console --port 3114 \
  --engine-port 3111 \
  --ws-port 3112 \
  --bridge-port 49134

What you can do from the console:

Traces are already on:

iii-config.yaml ships with the iii-observability worker enabled (exporter: memory, sampling_ratio: 1.0, metrics + logs). No extra config needed; the moment agentmemory starts, every memory operation emits a trace span and a structured log the console can read.

If you want to export to Jaeger/Honeycomb/Grafana Tempo instead, change exporter: memory to exporter: otlp and set the collector endpoint per iii's observability docs.

Heads-up: no auth is enforced on the console itself; keep it bound to 127.0.0.1 (the default) and never expose it publicly.

agentmemory is already a running iii instance. Three primitives (worker, function, trigger) compose the runtime; KV state, streams, and OTEL traces come from iii-state, iii-stream, and iii-observability workers that ship with iii. You didn't install Postgres, Redis, Express, pm2, or Prometheus, because iii replaces them.

That means one more command extends agentmemory with an entire new capability.

Extend agentmemory with one command Copy Section

iii worker add iii-pubsub          # fan memory writes out to every connected instance
iii worker add iii-cron            # scheduled consolidation, decay sweeps, snapshot rotation
iii worker add iii-queue           # durable retries for embedding + compression jobs
iii worker add iii-observability   # OTEL traces on every memory op (default on)
iii worker add iii-sandbox         # run recalled code inside an isolated microVM
iii worker add iii-database        # swap in a SQL-backed state adapter
iii worker add mcp                 # generic MCP host alongside the agentmemory MCP

Each iii worker add registers new functions and triggers into the same engine agentmemory is already running on. The viewer and console pick them up immediately: no reload, no new integration, no new container.

Full registry: workers.iii.dev. Every worker there composes through the same primitives agentmemory uses, and the agentmemory you already have is one of them.

What iii replaces Copy Section

184 source files · ~42,200 LOC · 1,674 tests · 264 functions · 50 KV scopes, all on three primitives. No agentmemory plugin install. The plugin system is iii itself.

LLM Providers Copy Section

agentmemory auto-detects from your environment. By default, no LLM calls are made unless you configure a provider or explicitly opt in to the Claude subscription fallback.

Local models (Ollama / LM Studio / vLLM) Copy Section

agentmemory talks to any OpenAI-API-compatible server, so anything that exposes /v1/chat/completions works without code changes. No paid keys, no cloud, no rate limits; runs entirely on your hardware.

Ollama (default port 11434):

ollama pull qwen3:8b   # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
ollama serve

# ~/.agentmemory/.env
OPENAI_API_KEY=ollama                          # any non-empty string; Ollama ignores it
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3:8b

LM Studio (default port 1234):

Open LM Studio → Local Server tab → Start Server. Pick any chat model from the picker (Qwen 3, gpt-oss, DeepSeek R1, etc.).

# ~/.agentmemory/.env
OPENAI_API_KEY=lmstudio                        # any non-empty string; LM Studio ignores it
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen3-8b                          # match the model name from LM Studio

vLLM / llama.cpp / Text Generation Inference: same shape. Point OPENAI_BASE_URL at whatever URL your server exposes and set OPENAI_MODEL to a name your server will accept.

Model picks for memory work: compression and summarization are short tasks (<2K tokens in, <500 tokens out) where a 7B instruct model is plenty. Recommendations:

Qwen 3 models think by default and can burn the whole token budget on reasoning before any output. Set AGENTMEMORY_LLM_NOTHINK=1 to append /no_think to graph-extraction prompts, and raise MAX_TOKENS (16384 works) if extractions come back empty.

Reasoning-class models (o1-style with `` blocks) can return empty content with a reasoning field your local server may not surface. If extractions come back blank, switch to a non-reasoning model first. The OPENAI_REASONING_EFFORT=none env can also disable thinking on Ollama Cloud thinking models that mirror the OpenAI reasoning schema.

Local embeddings ship out of the box via @huggingface/transformers: EMBEDDING_PROVIDER=local (default) gives you Xenova/all-MiniLM-L6-v2 (384-dim) entirely on-device. No extra config needed.

Cost-aware model selection Copy Section

Background compression runs on every observation, so model choice meaningfully changes monthly spend. Captured workload data: 635 requests / 888K tokens / 35 hours of active use, run against three OpenRouter models at 2026-05-23 pricing.

Measured rows come from the captured run; (est.) rows scale the same token mix by each model's list price.

agentmemory prints a runtime warning when OPENROUTER_MODEL matches a premium-tier pattern. Set AGENTMEMORY_SUPPRESS_COST_WARNING=1 to silence once you've made an informed choice.

Quality vs cost tradeoff for memory work: compression is a summarization task with relatively loose quality bars (the agent re-reads the summary, not the user). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder land within rounding error of Sonnet on this task while costing 10-70× less. Save the premium-tier models for queries you read directly.

Sources: OpenRouter pricing for Claude Sonnet 5, DeepSeek V4 Flash, DeepSeek pricing notes.

Multi-agent memory (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`) Copy Section

In multi-agent setups where several roles share one agentmemory server (architect / developer / reviewer / researcher / support-agent), AGENT_ID tags every write with the role that made it. AGENTMEMORY_AGENT_SCOPE controls whether recall filters by that tag.

TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated  # optional; default "shared"

Two modes:

What gets tagged when AGENT_ID is set: Session.agentId, RawObservation.agentId, CompressedObservation.agentId, Memory.agentId. The role flows from api::session::start → mem::observe → mem::compress → KV.

What gets filtered in isolated mode: mem::smart-search, /agentmemory/memories, /agentmemory/observations, /agentmemory/sessions. Each endpoint accepts ?agentId=<role> to override per-request, and ?agentId=* to opt out of the env scope entirely. /memories also accepts ?includeOrphans=true to surface pre-AGENT_ID memories whose agentId is undefined.

Per-call override at the SDK / REST layer: every mutating endpoint (/session/start, /remember) accepts an agentId field in the request body that wins over the env. Useful for runtimes routing many roles through one server process. The MCP memory_save tool exposes the same agentId field, the standalone stdio server forwards both agentId and project, and saved memories carry agentId into the search index, so agent-scoped search covers memories as well as observations.

When AGENT_ID is unset, memory remains unscoped (legacy behavior, no tags, no filters).

Ports Copy Section

agentmemory + iii-engine bind four ports by default. If a restart fails with port in use, this table tells you which process to look for.

Stale-process cleanup when ports stay bound after a crashed run:

# macOS / Linux — find whatever is on each port and kill it
lsof -i :3111,3112,3113,49134
pkill -f agentmemory || true
pkill -f 'iii ' || true

# Windows
netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID

agentmemory stop reaps both the worker and the engine pidfile cleanly on graceful shutdown. In Docker mode it tears down only agentmemory's own compose services and reaps the native worker before the Docker teardown; the CLI also refuses to adopt or signal Docker or VM port holders (Docker backend, vpnkit, colima) as the native engine unless --force is passed. The manual cleanup above is only for the post-crash case where neither pidfile is left behind.

Config File Copy Section

Put agentmemory runtime configuration in ~/.agentmemory/.env instead of exporting variables in every shell. If the viewer shows a setup hint like export ANTHROPIC_API_KEY=..., copy it into this file as ANTHROPIC_API_KEY=... without the export prefix, then restart agentmemory.

Process environment variables still work and take precedence over values in the file.

On Windows, the same file lives at %USERPROFILE%\.agentmemory\.env:

New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env

To test with a Claude Code Pro/Max subscription instead of an API key, opt in explicitly:

AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true

Consolidation (graph nodes, lessons, crystals) is on by default whenever an LLM provider is configured. Explicitly opt out with CONSOLIDATION_ENABLED=false if you want LLM-free operation. Graph extraction is a separate flag:

GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false   # opt out of auto-consolidation

Environment Variables Copy Section

Create ~/.agentmemory/.env:

/* Detailed source-code truncated for AI context efficiency. */

130 endpoints on port 3111. The REST API binds to 127.0.0.1 by default. Protected endpoints require Authorization: Bearer <secret> when AGENTMEMORY_SECRET is set, and mesh sync endpoints require AGENTMEMORY_SECRET on both peers.

Key endpoints

Full endpoint list: src/triggers/api.ts

npm run dev               # Hot reload
npm run build             # Production build
npm test                  # 1,674 tests
npm run test:integration  # API tests (requires running services)

Prerequisites: Node.js >= 20, iii-engine or Docker

Apache-2.0

File: benchmark/README.md Copy Chapter

benchmark/

Two kinds of numbers live in this directory:

1. Quality / retrieval — longmemeval-bench.ts, quality-eval.ts,
   real-embeddings-eval.ts, scale-eval.ts. Recall, precision, token
   savings. Documented in LONGMEMEVAL.md, QUALITY.md,
   REAL-EMBEDDINGS.md, SCALE.md.

2. Load shape — load-100k.ts. p50 / p90 / p99 latency and
   throughput against a running daemon. This is the file you want when
   somebody asks "what's p99 at 100k memories under concurrency 100?".

load-100k.ts Copy Chapter

Hand-rolled, dependency-free load harness. Issues real HTTP against a
local agentmemory daemon at http://localhost:3111, records per-request
latency with performance.now(), and writes a JSON report per run.

What it measures Copy Section

For each cell in the matrix (N, concurrency, endpoint) it records:

• p50_ms, p90_ms, p99_ms — nearest-rank percentiles.
• min_ms, max_ms, ops, errors.
• throughput_per_sec — wall-clock ops / sec for that cell.

Default matrix:

• N ∈ {1000, 10000, 100000} — number of memories seeded before the
  cell runs.
• C ∈ {1, 10, 100} — concurrent in-flight requests during the cell.
• Endpoints under test:
  • POST /agentmemory/remember
  • POST /agentmemory/smart-search
  • GET /agentmemory/memories?latest=true

Each cell issues BENCH_OPS=200 requests by default — enough samples
for stable p99 without dragging a 100k-seed run past tens of minutes.

Why p99 is the number that matters Copy Section

p50 tells you the median request feels fast. p90 tells you the bulk of
requests feel fast. p99 tells you the request your tail user hits when
they really need it feels fast. Capacity planning lives here — if you
want to size a fleet, scale your daemon, or set an SLO, p99 is the
number to plan against. p50 will lie to you.

Running it Copy Section

# 1. Start the daemon however you normally do (npx, Docker, etc.)
npx @agentmemory/agentmemory

# 2. From the repo root, in another shell:
npm run bench:load

To override the matrix:

BENCH_N=1000 BENCH_C=1,10 BENCH_OPS=100 npm run bench:load

To have the harness spawn a daemon for the run (after npm run build):

AGENTMEMORY_BENCH_AUTOSTART=1 npm run bench:load

Other env knobs (see the file header for the canonical list):

• AGENTMEMORY_URL — base URL of the daemon (default
  http://localhost:3111).
• BENCH_SEED — seed for the mulberry32 content RNG. Same seed +
  same daemon build = byte-identical seed corpus.
• BENCH_OUT_DIR — where the JSON report lands (default
  benchmark/results/).

Where results land Copy Section

benchmark/results/load-100k-<short-git-sha>.json. The harness
mkdir -ps the directory. The file has a schema_version: 1 field so
future format changes don't silently break consumers.

Content generation is seedable Copy Section

Synthetic memory content is built from a small noun / verb / concept
vocabulary fed by a mulberry32(BENCH_SEED) PRNG. Same seed + same
build = same corpus. The point isn't "realistic" content (there isn't
one realistic content); the point is reproducibility — re-running
the harness against the same git sha should give the same content
mixture going in, so latency variance comes from the daemon and not
from JSON payload jitter.

Publishing numbers per release Copy Section

The release flow appends a ## Performance section to CHANGELOG.md
referencing the JSON in benchmark/results/ for that release's git
sha. p99 is the headline number; the JSON is the receipt.

File: deploy/railway/README.md Copy Chapter

Deploy agentmemory on Railway

This template runs agentmemory on a single Railway service with a
persistent volume mounted at /data. The HMAC secret is generated on
first boot and persisted to the volume — you read it once from the
deploy logs and copy it into your client.

What you get Copy Chapter

• A public HTTPS endpoint serving the agentmemory REST API on port 3111
• A persistent Railway Volume at /data for memories, BM25 index, and
  stream backlog
• Railway healthcheck against /agentmemory/livez
• The HMAC bearer secret is generated on first boot inside the
  container and persisted to /data/.hmac (chmod 600); the operator
  copies it from the deploy logs once.
• The deploy uses requiredMountPath: /data so Railway refuses to
  start the service if no volume is attached at that path — first
  deploy must create the volume from the dashboard.

Deploy via Railway dashboard Copy Chapter

1. Click Deploy from GitHub in the Railway dashboard and pick the
   rohitg00/agentmemory repo.
2. Set the Config-as-Code Path under the service Settings to
   deploy/railway/railway.json. Railway picks up the Dockerfile path
   from there.
3. Open the service's Volumes tab and add a volume mounted at
   /data (Railway volumes are configured in the dashboard or via
   railway volume add, not in railway.json).
4. Click Deploy.

Deploy via Railway CLI Copy Chapter

# Install: https://docs.railway.com/guides/cli
railway login
railway init                                            # link a new project
railway up --service agentmemory                        # builds + deploys
railway volume add --service agentmemory --mount /data  # attach persistent volume
railway redeploy                                        # restart with the volume

Capture the HMAC secret Copy Chapter

After the first deploy succeeds, open the service's Deploy Logs:

railway logs --service agentmemory | grep AGENTMEMORY_SECRET=

You will see exactly one line of the form AGENTMEMORY_SECRET=<64 hex chars>.
Copy it into your client environment. The secret is never printed again
on subsequent boots.

Verify the deployment Copy Chapter

curl https://<your-service>.up.railway.app/agentmemory/livez
# {"status":"ok"}

For an authenticated call, your client must send Authorization: Bearer <secret>.

Viewer access (port 3113 stays internal) Copy Chapter

Railway only exposes the single public port from your service's
PORT env var (which we map to 3111). The viewer stays bound to
localhost inside the container. railway ssh is an interactive shell
only — it does not support -L-style port forwarding, so reach the
viewer with one of the following.

Quick in-container check:

railway ssh --service agentmemory
# inside the container:
curl http://localhost:3113

Browser session — option A (TCP Proxy, recommended): in the Railway
dashboard, open the service's Settings → Networking tab and add a
TCP Proxy for container port 3113. Railway returns a public
host/port pair you can hit directly from your browser. Pair it with the
HMAC bearer-auth header so the viewer is not anonymously reachable.

Browser session — option B (in-container sshd): add an openssh-server
process to the image and start it from entrypoint.sh on a fixed port,
expose that port through a second Railway TCP Proxy, then use a native
ssh -L 3113:localhost:3113 -p from your laptop.
This is the heavier path; option A is what most users will want.

Rotate the HMAC secret Copy Chapter

railway ssh --service agentmemory
rm /data/.hmac
exit
railway redeploy --service agentmemory
railway logs --service agentmemory | grep AGENTMEMORY_SECRET=

Update every client with the new secret. Old tokens stop working
immediately.

Back up `/data` Copy Chapter

railway ssh --service agentmemory -- "tar czf - /data" > agentmemory-$(date +%Y%m%d).tar.gz

To restore on a fresh volume:

cat agentmemory-YYYYMMDD.tar.gz | railway ssh --service agentmemory -- "tar xzf - -C /"
railway redeploy --service agentmemory

Cost floor and egress Copy Chapter

• Hobby plan: $5/month flat, includes $5 of usage.
• agentmemory at idle plus a 1 GB volume typically uses $3–$6 of usage
  per month on the smallest instance, so most users stay near the $5
  floor.
• Egress: $0.10/GB after the bundled allowance.

See https://railway.com/pricing for the current rate card.

Known caveats Copy Chapter

• Railway volumes do not auto-snapshot. Take your own backups (above)
  or use the dashboard's manual snapshot feature.
• The Dockerfile builds on Railway's builder on every deploy. First
  deploy is ~2 minutes; cached layers make subsequent rebuilds quick.
  Pin AGENTMEMORY_VERSION / III_VERSION build args in the
  service's Variables tab to lock a specific release.

File: deploy/fly/README.md Copy Chapter

Deploy agentmemory on fly.io

This template runs agentmemory on a single fly.io machine with a 1 GB
persistent volume mounted at /data. The HMAC secret is generated on
first boot and persisted to the volume — you capture it from the deploy
logs exactly once.

What you get Copy Chapter

• A public HTTPS endpoint serving the agentmemory REST API on port 3111
• A 1 GB Fly Volume at /data for memories, BM25 index, and stream backlog
• auto_stop_machines = "stop" and min_machines_running = 0 — the
  machine sleeps when idle, so cost floor approaches $0 for low traffic
• HTTP healthcheck at /agentmemory/livez every 30 s
• The HMAC bearer secret is generated on first boot inside the
  container and persisted to /data/.hmac (chmod 600); the operator
  copies it from the deploy logs once.

One-time setup Copy Chapter

Pick a unique Fly app name first — agentmemory itself is likely taken.
Every command below references $APP, so set it once and the rest of the
flow stays consistent:

# 1. Install flyctl: https://fly.io/docs/flyctl/install/
# 2. Pick your unique app name (and matching volume name):
export APP="agentmemory-$(whoami)"     # or any other globally-unique name
export VOLUME="${APP//-/_}_data"       # Fly volume names can't contain '-'

# 3. From this directory:
fly launch --copy-config --no-deploy --name "$APP"

# 4. Create the volume in the same region as the app:
fly volumes create "$VOLUME" --region iad --size 1

# 5. Deploy:
fly deploy --app "$APP"

If fly launch reports the name is taken, pick another value for $APP,
re-export, and re-run.

Capture the HMAC secret Copy Chapter

Right after the first deploy succeeds:

fly logs --app "$APP" | grep -A1 AGENTMEMORY_SECRET=

You will see exactly one line of the form AGENTMEMORY_SECRET=<64 hex chars>.
Copy it into your client environment (~/.bashrc, Claude Desktop config,
the viewer unlock prompt, etc.). The secret is never printed again on
subsequent boots.

If the first-boot log line is no longer available, read the persisted
secret from the mounted volume:

fly ssh console --app "$APP" -C "sh -lc 'cat /data/.hmac'"

Verify the deployment Copy Chapter

curl "https://$APP.fly.dev/agentmemory/livez"
# {"status":"ok"}

For an authenticated call, your client must send Authorization: Bearer <secret>.

Viewer access (port 3113 stays internal) Copy Chapter

The viewer port is intentionally not exposed publicly. Tunnel to it:

fly proxy 3113:3113 --app "$APP"
# then open http://localhost:3113

fly proxy opens an mTLS WireGuard channel to the machine, so the
viewer's bearer token still has to ride a loopback connection on your
laptop — the v0.9.12 plaintext-bearer guard stays satisfied.

The entrypoint sets AGENTMEMORY_VIEWER_HOST=:: only when it detects
Fly's runtime variables (FLY_APP_NAME / FLY_ALLOC_ID). That makes
the viewer listen on the machine's fly-local-6pn WireGuard interface
as well as loopback so fly proxy can reach it. The same branch
pre-seeds VIEWER_ALLOWED_HOSTS=localhost:3113,127.0.0.1:3113,[::1]:3113,
which are the Host headers fly proxy 3113:3113 actually emits on
your laptop.

When AGENTMEMORY_VIEWER_HOST is non-loopback the viewer enforces two
extra guards: it refuses to start unless VIEWER_ALLOWED_HOSTS is
explicitly set, and every request to /agentmemory/* must present
Authorization: Bearer $AGENTMEMORY_SECRET. Static HTML and the
favicon are still served unauthenticated. If a proxied viewer request
gets a 401, the browser UI prompts for AGENTMEMORY_SECRET and stores
it in session storage so subsequent viewer API calls include the bearer.
Use the value printed in the first-boot logs or read /data/.hmac
inside the machine.

Security warning. Setting AGENTMEMORY_VIEWER_HOST=0.0.0.0 or
:: turns the viewer into a network-reachable proxy that signs every
upstream call with AGENTMEMORY_SECRET. Never enable that outside a
network you trust (Fly's WireGuard mesh in this template), and never
set it in a plain docker run -p 3113:3113 … on a shared host — the
entrypoint deliberately skips the override when Fly env vars are
absent so a plain Docker pull stays loopback-only.

Rotate the HMAC secret Copy Chapter

fly ssh console --app "$APP"
rm /data/.hmac
exit
fly machine restart <machine-id>
fly logs --app "$APP" | grep AGENTMEMORY_SECRET=

Update every client with the new secret. Old tokens stop working
immediately.

Back up `/data` Copy Chapter

fly ssh console --app "$APP" -C "tar czf - /data" > "$APP-$(date +%Y%m%d).tar.gz"

To restore on a fresh machine:

cat "$APP-YYYYMMDD.tar.gz" | fly ssh console --app "$APP" -C "tar xzf - -C /"
fly machine restart <machine-id>

Cost floor and egress Copy Chapter

• Idle (machine stopped): the volume costs ~$0.15/GB/month. A 1 GB
  volume is roughly $0.15/month.
• Active (machine running on shared-cpu-1x with 512 MB): about
  $1.94/month if it ran 24/7; in practice auto_stop_machines keeps
  that well under $1.
• Outbound bandwidth: 100 GB/month free on the Hobby plan, then $0.02/GB
  in North America / Europe.

See https://fly.io/docs/about/pricing/ for the up-to-date rate card.

Known caveats Copy Chapter

• The volume lives in one region. To survive a region outage, create a
  second volume in another region and update primary_region after the
  failover, or take snapshots with fly volumes snapshots create.
• The Dockerfile builds in the Fly Builder on every deploy — first
  build is ~30 seconds; cached layers shrink rebuilds to under 10
  seconds. Image is ~114 MB.
• First deploy lands on a shared IPv4 + dedicated IPv6 by default
  (free). If you need a dedicated IPv4 for legacy clients without SNI,
  run fly ips allocate-v4 --app "$APP" — costs $2/month.
• Cold-start (from machine launch to passing /agentmemory/livez) is
  ~9 seconds measured. grace_period = "30s" on the health check
  gives a 3x safety margin.
• Bump AGENTMEMORY_VERSION or III_VERSION in the Dockerfile to
  upgrade. fly deploy --build-arg AGENTMEMORY_VERSION=<x> also works
  for a one-off without editing the file.

File: deploy/coolify/README.md Copy Chapter

Deploy agentmemory on Coolify

Coolify is an open-source, self-hosted
Heroku/Render alternative that you run on your own VPS. This template
deploys agentmemory as a Coolify Application backed by a Docker
Compose stack — Coolify handles TLS termination, persistent volume
provisioning, log aggregation, and the deploy webhook for you.

What you get Copy Chapter

• A public HTTPS endpoint serving the agentmemory REST API behind
  Coolify's built-in Traefik/Caddy proxy. The container port (3111)
  is exposed to the proxy network only — never bound to the host — so
  TLS termination and domain routing stay under proxy control.
• A persistent Docker volume backing /data for memories, BM25 index,
  and stream backlog. Coolify auto-prefixes the volume name with the
  application's UUID so the data survives redeploys.
• An HTTP health-check at /agentmemory/livez declared in the
  Dockerfile (HEALTHCHECK directive). Coolify reuses it for
  rolling-deploy decisions.

One-time setup Copy Chapter

1. Open your Coolify dashboard and click + New → Application.
2. Source: pick Public Repository. Paste:
   text Copy

   https://github.com/rohitg00/agentmemory

   Branch: main.
3. Build Pack: select Docker Compose.
4. Base Directory: deploy/coolify
5. Compose Path: docker-compose.yml
6. Click Save, then on the application settings screen set a
   Domain in the form https://<your-fqdn>:3111 (the :3111
   suffix tells Coolify's proxy which container port to forward to;
   it still serves over 443/80 publicly).
7. Click Deploy.

That's it. Coolify clones the repo, builds the Dockerfile under
deploy/coolify/, provisions the agentmemory-data named volume on
the host, attaches Traefik (or Caddy) for the public domain, and starts
the service. The container is reachable only through the proxy — there
is no published host port.

Capture the HMAC secret Copy Chapter

Once the deploy logs show the service is up, open the application's
Logs tab in Coolify and search for AGENTMEMORY_SECRET=. You will
see exactly one line of the form AGENTMEMORY_SECRET=<64 hex chars>.
Copy it into your client environment (~/.bashrc, Claude Desktop
config, etc.). The secret is never printed again on subsequent boots.

Verify the deployment Copy Chapter

curl "https://<your-coolify-domain>/agentmemory/livez"
# {"status":"ok"}

For an authenticated call, your client must send
Authorization: Bearer <secret>.

Viewer access (port 3113 stays internal) Copy Chapter

The viewer port is not exposed by the compose file on purpose — it
holds the unauthenticated admin surface in older releases and the
proxied surface in current ones, neither of which belongs on the open
internet. Two paths to reach it:

Option A — SSH tunnel from the Coolify host. Coolify gives you SSH
access to the underlying VPS. From your laptop:

ssh -L 3113:127.0.0.1:3113 @<coolify-host>
# inside the SSH session, find the container:
docker ps --filter name=agentmemory --format "{{.Names}}"
# tunnel into the container's port from the host:
docker exec -it <container-name> sh -c "curl http://localhost:3113"

Cleaner version: bind the container's 3113 to the host's loopback by
adding - "127.0.0.1:3113:3113" to the ports: block in
docker-compose.yml, redeploy, then ssh -L 3113:127.0.0.1:3113 @<host> is enough.

Option B — expose 3113 as a second Coolify domain protected by HTTP
basic auth. Coolify's per-service routing supports adding a second
public endpoint with basic-auth middleware. Useful if you want to
share the viewer with a teammate without giving them SSH.

Rotate the HMAC secret Copy Chapter

ssh @<coolify-host>
docker exec -it <container-name> sh -c "rm /data/.hmac"
exit

Then click Redeploy in the Coolify dashboard. The next boot prints
a fresh secret to the logs.

Back up `/data` Copy Chapter

Coolify exposes the named volume on the host filesystem under
/var/lib/docker/volumes/_agentmemory-data/_data. Back it
up with your existing host-level snapshot tooling (Restic, Borg,
rsync, BTRFS snapshots, etc.) or via Coolify's built-in Backups
feature for Docker volumes.

Cost floor and resources Copy Chapter

• Hardware: the agentmemory container idles at ~150 MB RSS, climbs
  to ~400 MB under steady traffic. The bundled iii engine adds another
  ~80 MB. A 1 vCPU / 1 GB VPS is comfortably enough for a personal
  install.
• VPS providers commonly paired with Coolify: Hetzner CX22
  (~€3.79/month), DigitalOcean Basic Droplet ($6/month), Vultr Cloud
  Compute ($6/month). Coolify itself is free.
• Volume storage: tied to whatever block storage the VPS provides;
  typically pennies per GB-month.

Known caveats Copy Chapter

• The Dockerfile builds on the Coolify host on every deploy. First
  deploy takes ~2 minutes; cached layers shrink subsequent rebuilds to
  under 30 seconds. Pin AGENTMEMORY_VERSION and III_VERSION in
  docker-compose.yml's build.args block to lock a specific release.
• Coolify's Persistent Storage tab will show agentmemory-data as a
  managed volume — do not delete it from the dashboard if you want
  your memories to survive a redeploy.
• arm64 hosts work — the iii binary selection in the Dockerfile uses
  uname -m and downloads the matching tarball.

File: deploy/render/README.md Copy Chapter

Deploy agentmemory on Render

This template runs agentmemory on a single Render Web Service with a
persistent disk mounted at /data. The HMAC secret is generated on
first boot and persisted to the disk — you capture it from the deploy
logs exactly once.

What you get Copy Chapter

• A public HTTPS endpoint serving the agentmemory REST API on port 3111
  (Render injects PORT defaulting to 10000; we override it to 3111
  via envVars so the published port matches the container's bind)
• A 1 GB persistent disk at /data for memories, BM25 index, and
  stream backlog
• Render healthcheck against /agentmemory/livez
• The HMAC bearer secret is generated on first boot inside the
  container and persisted to /data/.hmac (chmod 600); the operator
  copies it from the deploy logs once.

Deploy via Render Blueprint Copy Chapter

Render's one-click deploy button only auto-detects render.yaml at the
repository root, which the agentmemory repo keeps clean. Use the
dashboard's manual Blueprint flow instead:

1. Push the deploy/render/ directory to a Git provider Render can
   reach (a fork of rohitg00/agentmemory works).
2. In the Render dashboard, click New + → Blueprint.
3. Point Render at the repo and the path deploy/render/render.yaml.
4. Render reads the Blueprint, provisions the disk, builds the
   Dockerfile, and starts the service. The whole flow takes 3–5
   minutes on the first run.

Deploy via Render Deploy Hook (one-click) Copy Chapter

Once the Blueprint exists in your account, generate a Deploy Hook URL
in the service settings. Future deploys are a single curl call:

curl "https://api.render.com/deploy/srv-XXYYZZ?key=AABBCC"

To pin a specific @agentmemory/agentmemory release, set the
AGENTMEMORY_VERSION build arg in the service's Environment tab
before the next deploy. Same for III_VERSION.

Capture the HMAC secret Copy Chapter

After the first deploy succeeds, open the service's Logs tab and
search for AGENTMEMORY_SECRET=. You will see exactly one line of the
form AGENTMEMORY_SECRET=<64 hex chars>. Copy it into your client
environment. The secret is never printed again on subsequent boots.

Verify the deployment Copy Chapter

curl https://agentmemory.onrender.com/agentmemory/livez
# {"status":"ok"}

For an authenticated call, your client must send Authorization: Bearer <secret>.

Viewer access (port 3113 stays internal) Copy Chapter

Render only exposes one public port per service, and we use it for
3111. The viewer port stays bound to localhost inside the container.
Reach it via Render's SSH:

# Settings → SSH → enable for your service, copy the connection command
ssh srv-XXYYZZ@ssh.<region>.render.com -L 3113:localhost:3113
# now http://localhost:3113 in your browser hits the in-container viewer

Rotate the HMAC secret Copy Chapter

ssh srv-XXYYZZ@ssh.<region>.render.com
rm /data/.hmac
exit
# trigger a redeploy from the Render dashboard or via the Deploy Hook

After the redeploy, grab the new secret from the logs and update every
client. Old tokens stop working immediately.

Back up `/data` Copy Chapter

ssh srv-XXYYZZ@ssh.<region>.render.com "tar czf - /data" > agentmemory-$(date +%Y%m%d).tar.gz

Render also takes daily snapshots of persistent disks automatically on
paid plans — the SSH tarball is a belt-and-braces option you can ship
off-platform.

Cost floor and egress Copy Chapter

• Starter plan web service: $7/month (0.5 CPU, 512 MB RAM).
• 1 GB persistent disk: $0.25/GB/month, so $0.25/month for the default.
• Bandwidth: 100 GB outbound included, then $0.10/GB.

See https://render.com/pricing for the current rate card.

Known caveats Copy Chapter

• Render Free tier does not support persistent disks. The Starter plan
  ($7/month) is the minimum.
• Render restarts the service on every deploy. The HMAC secret survives
  because it lives on the disk, but expect a 10–30 s gap of 502s
  during rollouts.
• Render runs amd64 only for web services. The Dockerfile selects the
  matching iii binary automatically via uname -m.

File: deploy/README.md Copy Chapter

One-click deploy templates

Stand up agentmemory on managed infrastructure without rolling your own
Docker host. Each template ships a self-contained Dockerfile that pulls
@agentmemory/agentmemory from npm at build time and copies the iii
engine binary in from the official iiidev/iii image — no pre-built
agentmemory image required. Storage mounts at /data; an HMAC secret
is generated by the first-boot entrypoint and persisted to the volume.
The entrypoint overwrites the npm-bundled iii config with a
deploy-tuned one that binds 0.0.0.0 and uses absolute /data paths,
then drops privileges from root to node via gosu before
exec'ing the agentmemory CLI.

What every template guarantees Copy Chapter

• Volume mounted at /data. Matches the path the engine has used
  since v0.9.10.
• HMAC secret generated on first boot via openssl rand -hex 32,
  written to /data/.hmac with chmod 600, and printed to stdout
  exactly once so the operator can capture it from the deploy logs.
  Subsequent boots load the secret from the file. The secret is never
  committed to a config file or set as a platform env var.
• Only port 3111 is exposed publicly. The viewer on port 3113
  stays bound to the container's localhost. Reach it via SSH tunnel
  (see each platform's README).
• TLS upstream of the container. Every managed platform terminates
  TLS at its edge proxy; the templates publish a single internal port
  (3111) to that proxy, never to the host. Integration plugins
  configured with AGENTMEMORY_REQUIRE_HTTPS=1 will refuse to send the
  bearer over plaintext HTTP to a non-loopback host, so a
  misconfigured TLS layer fails loud instead of silently leaking the
  secret.

Pick a platform Copy Chapter

• Pick fly.io if you want the lowest idle cost and don't mind a
  cold-start latency hit on the first request after sleep.
• Pick Railway if you want a clicky dashboard flow and a flat
  monthly bill.
• Pick Render if you want the most "set it and forget it"
  Blueprint flow with automatic disk snapshots on paid plans.
• Pick Coolify if you already run a VPS and want a self-hosted
  control plane — same Docker Compose stack, no third-party host has
  your memories.

All four give you the same agentmemory API at the same port (3111)
with the same auth model. Migrating between them later is a tar of
/data and a re-import — see each platform's README for the exact
commands.

Optional: LLM + embedding provider keys Copy Chapter

Every template runs out of the box without any LLM or embedding key —
search falls back to BM25-only mode and synthetic (zero-LLM)
compression keeps memories indexable. To unlock LLM-powered
compression and hybrid (BM25 + vector) recall, add one of the
following to your platform's environment variables (Fly:
flyctl secrets set; Railway / Render / Coolify: dashboard
Variables / Environment tab):

The defaults are intentionally conservative: provider keys default to
absent (no third-party calls), AGENTMEMORY_AUTO_COMPRESS is off,
and AGENTMEMORY_INJECT_CONTEXT is off. Opt in only after you've
confirmed your provider quota can absorb the workload.

Cold-start budget Copy Chapter

Measured against fly.io's iad region with a 1 GB volume:

machine image prepared :  5.1 s
volume mount + format  :  2.5 s
firecracker boot       :  1.0 s
entrypoint + chown     :  0.5 s
iii-engine ready       :  3.0 s
agentmemory worker reg :  2.0 s
─────────────────────────────────
healthcheck passes     : ~9-10 s

Every template's health-check grace_period (or compose
start_period) is set to 30 s for a 3x safety margin. Tune lower
once you've measured your own platform's image-pull characteristics.

File: examples/python/README.md Copy Chapter

Python usage via `iii-sdk`

agentmemory registers its core operations as iii functions (mem::remember,
mem::observe, mem::context, mem::smart-search, mem::forget). Any
language with an iii SDK can call them directly over the WebSocket transport
on ws://localhost:49134 — no separate REST client needed.

This example uses the official Python SDK.

Install Copy Chapter

pip install iii-sdk

Quickstart Copy Chapter

Start the agentmemory daemon (defaults to ws://localhost:49134, REST on
:3111):

npx -y @agentmemory/agentmemory

Then from Python:

from iii import register_worker

iii = register_worker("ws://localhost:49134")
iii.connect()

iii.trigger({
    "function_id": "mem::remember",
    "payload": {
        "project": "demo",
        "title": "auth-stack",
        "content": "Service uses HMAC bearer tokens; refresh every 24h.",
        "concepts": ["auth", "hmac", "refresh"],
    },
})

hits = iii.trigger({
    "function_id": "mem::smart-search",
    "payload": {"project": "demo", "query": "how do tokens refresh", "limit": 5},
})
print(hits)

Functions exposed Copy Chapter

The HTTP-trigger wrappers under api::* (callable via REST on :3111) exist
for the same operations if you need to reach the daemon from a host without an
iii runtime. Inside the iii ecosystem, calling the mem::* functions directly
is lower latency.

Files Copy Chapter

• quickstart.py — minimal save-then-search loop.
• observe_and_recall.py — observation ingest + context rendering at a token
  budget.

Both scripts assume the daemon is already running.

File: integrations/pi/README.md Copy Chapter

 agentmemory for pi

Quick setup Copy Chapter

Start the agentmemory server in a separate terminal:

npx @agentmemory/agentmemory

Copy this folder into pi's global extensions directory:

mkdir -p ~/.pi/agent/extensions/agentmemory
cp integrations/pi/index.ts ~/.pi/agent/extensions/agentmemory/index.ts

Then enable it in ~/.pi/agent/settings.json if you prefer explicit loading:

{
  "extensions": ["~/.pi/agent/extensions/agentmemory"]
}

If you place it under ~/.pi/agent/extensions/agentmemory/, pi will also auto-discover it and /reload can hot-reload it.

What it adds Copy Chapter

• memory_health — confirm the shared memory server is reachable
• memory_search — search prior decisions, bugs, workflows, and preferences
• memory_save — write durable facts back to long-term memory
• /agentmemory-status — check health from inside pi
• before_agent_start recall — injects relevant memories into the prompt
• agent_end capture — saves completed conversation turns back to agentmemory

Environment variables Copy Chapter

Smoke test Copy Chapter

Run pi and ask it to use the memory_health tool, or call the command directly:

/agentmemory-status

You should see agentmemory healthy and a footer status like 🧠 agentmemory.

Notes Copy Chapter

• This extension uses pi's extension API, not MCP, so it can hook directly into the agent lifecycle.
• One local agentmemory server can be shared across pi, pi2, Hermes, OpenClaw, Claude Code, Codex CLI, and Gemini CLI.

See also Copy Chapter

• agentmemory main README
• Hermes integration
• OpenClaw integration

File: integrations/openclaw/README.md Copy Chapter

 agentmemory for OpenClaw

Install it in 30 seconds Copy Chapter

Paste this prompt into OpenClaw and it does the whole setup for you:

Install agentmemory for OpenClaw. Run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server on localhost:3111.

For zero-code setup, add this MCP server so OpenClaw gets all 43 memory tools:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}

For deeper memory integration, copy `integrations/openclaw` from the agentmemory repo to `~/.openclaw/extensions/agentmemory`, then enable it in `~/.openclaw/openclaw.json`:

{
  "plugins": {
    "slots": {
      "memory": "agentmemory"
    },
    "entries": {
      "agentmemory": {
        "enabled": true,
        "config": {
          "base_url": "http://localhost:3111",
          "token_budget": 2000,
          "min_confidence": 0.5,
          "fallback_on_error": true,
          "timeout_ms": 5000
        }
      }
    }
  }
}

Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer.

That's it. OpenClaw handles the rest.

Option 1: MCP server (zero code) Copy Chapter

Start the agentmemory server in a separate terminal:

npx @agentmemory/agentmemory

Then add to your OpenClaw MCP config:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"]
    }
  }
}

OpenClaw now has access to all 43 MCP tools including memory_recall, memory_save, memory_smart_search, memory_timeline, memory_profile, and more.

Option 2: OpenClaw memory plugin (deeper integration) Copy Chapter

Copy this folder into OpenClaw's extension directory:

mkdir -p ~/.openclaw/extensions
cp -r integrations/openclaw ~/.openclaw/extensions/agentmemory

Then enable it in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "slots": {
      "memory": "agentmemory"
    },
    "entries": {
      "agentmemory": {
        "enabled": true,
        "config": {
          "base_url": "http://localhost:3111",
          "token_budget": 2000,
          "min_confidence": 0.5,
          "fallback_on_error": true,
          "timeout_ms": 5000
        }
      }
    }
  }
}

What the plugin does:

• claims the plugins.slots.memory = "agentmemory" slot via api.registerMemoryCapability({ promptBuilder }) so OpenClaw recognises it as the active memory plugin
• recalls relevant long-term memory before the agent starts (via the before_agent_start hook)
• captures completed conversation turns after the agent finishes (via the agent_end hook)

OpenClaw blocks conversation-reading hooks from non-bundled plugins by default. Allow it once in openclaw.json so turn capture works:

{
  "plugins": {
    "allow": ["agentmemory"],
    "entries": { "agentmemory": { "hooks": { "allowConversationAccess": true } } }
  }
}

• shares the same backend with Claude Code, Codex CLI, Gemini CLI, Hermes, pi, and other agents

Memory runtime (current scope) Copy Section

The plugin currently registers a promptBuilder only — not a full MemoryPluginRuntime adapter. OpenClaw's MemoryRuntimeBackendConfig type today is { backend: "builtin" } or { backend: "qmd" }; both are openclaw-internal backends that don't fit agentmemory's external REST shape. The hook-driven recall + capture flow above is the working integration path. If you need OpenClaw's in-process memory-runtime APIs (e.g. getMemorySearchManager) backed by agentmemory, file an upstream request against openclaw for an "external" backend type and we'll wire runtime here once the contract supports it.

Troubleshooting Copy Chapter

Plugin validates but does not load — make sure the folder contains package.json, openclaw.plugin.json, and plugin.mjs, and that plugins.slots.memory is set to agentmemory.

plugins.slots.memory = "agentmemory" reports unavailable — upgrade to v0.9.11+. Older versions of this plugin registered hooks but never called api.registerMemoryCapability(...), so the memory-slot machinery did not consider the slot claimed. The current plugin registers a memory capability (prompt builder) at startup, which is the documented OpenClaw API for occupying the slot.

Connection refused on port 3111 — the agentmemory server is not running. Start it with npx @agentmemory/agentmemory.

No memories returned — open http://localhost:3113 and verify observations are being captured.

See also Copy Chapter

• agentmemory main README
• Hermes integration
• pi integration

License Copy Chapter

Apache-2.0 (same as agentmemory)

2. Official Technical Reference & Guides (rohitg00/docs) Copy Chapter

Mintlify Starter Kit

Click on Use this template to copy the Mintlify starter kit. The starter kit contains examples including

• Guide pages
• Navigation
• Customizations
• API Reference pages
• Use of popular components

Development Copy Section

Install the Mintlify CLI to preview the documentation changes locally. To install, use the following command

npm i mintlify

Run the following command at the root of your documentation (where mint.json is)

mintlify dev

Publishing Changes Copy Section

Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard.

Troubleshooting

• Mintlify dev isn't running - Run mintlify install it'll re-install dependencies.
• Page loads as a 404 - Make sure you are running in a folder with mint.json