Repository navigation
Detailed, self-updating skills covering the whole system #854
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| # Troubleshooting agentmemory skills | ||
|
|
||
| Shared recovery steps for all user-invocable agentmemory skills. Each skill's | ||
| Troubleshooting section points here instead of duplicating the block. | ||
|
|
||
| ## "MCP tool not available" | ||
|
|
||
| If a `memory_*` MCP tool does not appear, the stdio MCP shim never started. | ||
| Walk these in order: | ||
|
|
||
| 1. Run `/plugin list` in the host and confirm `agentmemory` shows as enabled. | ||
| 2. Restart the host. The plugin's `.mcp.json` is only read on startup, so a | ||
| freshly installed or re-enabled plugin will not register tools mid-session. | ||
| 3. Check `/mcp` and confirm the `agentmemory` server shows a live connection. | ||
|
|
||
| ## REST fallback | ||
|
|
||
| When the MCP tools stay unavailable but the daemon is running, call the REST | ||
| API directly: | ||
|
|
||
| 1. Set `AGENTMEMORY_URL` to the daemon base URL (default `http://localhost:3111`). | ||
| 2. Add `Authorization: Bearer $AGENTMEMORY_SECRET` ONLY when `AGENTMEMORY_SECRET` | ||
| is set. The default localhost daemon is open and rejects a stray header. | ||
|
|
||
| Endpoint map by skill: | ||
|
|
||
| | Skill | REST call | | ||
| | --------------- | --------------------------------------------------------------- | | ||
| | remember | `POST /agentmemory/remember` | | ||
| | recall | `POST /agentmemory/smart-search` | | ||
| | recap | `GET /agentmemory/sessions` + `POST /agentmemory/smart-search` | | ||
| | handoff | `GET /agentmemory/sessions` + `POST /agentmemory/smart-search` | | ||
| | session-history | `GET /agentmemory/sessions` | | ||
| | commit-context | `GET /agentmemory/session/by-commit?sha=<sha>` | | ||
| | commit-history | `GET /agentmemory/commits` (URL-encode every query param) | | ||
|
|
||
| The daemon reads `.mcp.json` on startup only, so any port or auth change needs a | ||
| restart before either transport sees it. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| # agentmemory connect adapters reference | ||
|
|
||
| Generated from `src/cli/connect/index.ts`. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing an adapter. | ||
|
|
||
| <!-- AUTOGEN:agents START - generated by scripts/skills/generate.ts, do not edit by hand --> | ||
| `agentmemory connect <agent>` wires the memory server into a host agent. 17 adapters: | ||
|
|
||
| | Agent | Name | Protocol | | ||
| | --- | --- | --- | | ||
| | Antigravity | `antigravity` | Using MCP via mcp_config.json. Antigravity replaces Gemini CLI (sunset 2026-06-18). | | ||
| | Claude Code | `claude-code` | Using MCP. Hooks are also available, see docs/claude-code.md. | | ||
| | Cline | `cline` | Using MCP via ~/.cline/mcp.json (CLI). VS Code users: add the same block via Cline Settings → MCP Servers → Edit JSON. | | ||
| | Codex CLI | `codex` | Using MCP. Hooks ship via the Codex plugin; on Codex Desktop, also pass --with-hooks to install the global hooks.json workaround for openai/codex#16430. | | ||
| | Continue | `continue` | Using MCP via ~/.continue/config.yaml (preferred) or config.json (legacy, only when no yaml). | | ||
| | GitHub Copilot CLI | `copilot-cli` | Using MCP. Install the plugin too for full hooks/skills coverage. | | ||
| | Cursor | `cursor` | Using MCP (the only protocol Cursor speaks). Memory bridge runs at :3111 underneath. | | ||
| | Droid (Factory.ai) | `droid` | Using MCP via ~/.factory/mcp.json. The `/mcp` slash command inside droid lists configured servers. | | ||
| | Gemini CLI | `gemini-cli` | Using MCP (the only protocol Gemini CLI speaks). Memory bridge runs at :3111 underneath. | | ||
| | Hermes Agent | `hermes` | Using MCP. Hooks are also available, see docs/hermes.md. | | ||
| | Kiro | `kiro` | Using MCP via ~/.kiro/settings/mcp.json (user-level). Workspace overrides live in .kiro/settings/mcp.json. | | ||
| | OpenClaw | `openclaw` | Using MCP. Hooks are also available, see docs/openclaw.md. | | ||
| | OpenHuman | `openhuman` | Using native hooks (REST API at :3111). MCP not required. | | ||
| | pi | `pi` | Using native hooks (REST API at :3111). MCP not required. | | ||
| | Qwen Code | `qwen` | Using MCP via ~/.qwen/settings.json. Qwen Code's hook system can also be wired separately, see docs. | | ||
| | Warp | `warp` | Using MCP via ~/.warp/.mcp.json. Skills auto-discover from .claude/skills/ if the Claude Code plugin is also installed. | | ||
| | Zed | `zed` | Using MCP via ~/.config/zed/settings.json (key: context_servers). | | ||
| <!-- AUTOGEN:agents END --> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| --- | ||
| name: agentmemory-agents | ||
| description: How agentmemory wires into host coding agents via the connect command. Use when installing agentmemory into a specific agent, when asked which agents are supported, or when a connect adapter writes the wrong config path. | ||
| user-invocable: false | ||
| --- | ||
|
|
||
| `agentmemory connect <agent>` merges the memory server into a host agent's config and preserves any existing servers. REST is the underlying protocol; for MCP-only hosts the adapter wires the stdio MCP bridge. | ||
|
|
||
| ## Quick start | ||
|
|
||
| ```bash | ||
| agentmemory connect claude-code # or cursor, codex, gemini-cli, ... | ||
| ``` | ||
|
|
||
| After wiring, restart the host or run its MCP reload (for example `/mcp` in Claude Code) so it picks up the server. Then confirm the agent lists agentmemory's tools. | ||
|
|
||
| ## Workflow | ||
|
|
||
| 1. Detect the calling agent. If unknown, default to `claude-code`. | ||
| 2. Run `agentmemory connect <name>` using a name from the table in REFERENCE.md. | ||
| 3. Verify: the host should show the full tool set with a server running. Only 7 tools means the MCP shim could not reach a server (see ../_shared/TROUBLESHOOTING.md). | ||
|
|
||
| ## Notes | ||
|
|
||
| - The action skills (remember, recall, and the rest) are installed separately with `npx skills add rohitg00/agentmemory`. `connect` makes tools available; skills teach the agent when to use them. | ||
| - Windows: use WSL2. Native Windows runs the server but `connect` is not supported there. | ||
|
|
||
| ## See also | ||
|
|
||
| - agentmemory-mcp-tools, agentmemory-rest-api, agentmemory-hooks. | ||
|
|
||
| ## Reference | ||
|
|
||
| The full adapter list with display names and protocol notes lives in REFERENCE.md, generated from `src/cli/connect/`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| --- | ||
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| # agentmemory configuration reference | ||
|
|
||
| Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded. | ||
|
|
||
| <!-- AUTOGEN:env START - generated by scripts/skills/generate.ts, do not edit by hand --> | ||
| Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 34 recognized variables: | ||
|
|
||
| - `AGENTMEMORY_AGENT_SCOPE` | ||
| - `AGENTMEMORY_ALLOW_AGENT_SDK` | ||
| - `AGENTMEMORY_AUTO_COMPRESS` | ||
| - `AGENTMEMORY_COMMIT_SHA` | ||
| - `AGENTMEMORY_COPILOT_MCP_BLOCK` | ||
| - `AGENTMEMORY_CWD` | ||
| - `AGENTMEMORY_DEBUG` | ||
| - `AGENTMEMORY_DROP_STALE_INDEX` | ||
| - `AGENTMEMORY_EXPORT_ROOT` | ||
| - `AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS` | ||
| - `AGENTMEMORY_FORCE_PROXY` | ||
| - `AGENTMEMORY_GRAPH_WEIGHT` | ||
| - `AGENTMEMORY_III_CONFIG` | ||
| - `AGENTMEMORY_III_VERSION` | ||
| - `AGENTMEMORY_IMAGE_EMBEDDINGS` | ||
| - `AGENTMEMORY_IMAGE_STORE_MAX_BYTES` | ||
| - `AGENTMEMORY_INJECT_CONTEXT` | ||
| - `AGENTMEMORY_LLM_TIMEOUT_MS` | ||
| - `AGENTMEMORY_MCP_BLOCK` | ||
| - `AGENTMEMORY_PROBE_TIMEOUT_MS` | ||
| - `AGENTMEMORY_PROJECT_NAME` | ||
| - `AGENTMEMORY_PROVIDER` | ||
| - `AGENTMEMORY_REFLECT` | ||
| - `AGENTMEMORY_SDK_CHILD` | ||
| - `AGENTMEMORY_SECRET` | ||
| - `AGENTMEMORY_SESSION_ID` | ||
| - `AGENTMEMORY_SLOTS` | ||
| - `AGENTMEMORY_SUPPRESS_COST_WARNING` | ||
| - `AGENTMEMORY_TOOLS` | ||
| - `AGENTMEMORY_URL` | ||
| - `AGENTMEMORY_USE_DOCKER` | ||
| - `AGENTMEMORY_VERBOSE` | ||
| - `AGENTMEMORY_VIEWER_HOST` | ||
| - `AGENTMEMORY_VIEWER_URL` | ||
| <!-- AUTOGEN:env END --> |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.