Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

fix: CLI help and docs papercuts (#897)

Rohit Ghumaref3dc7f8ece6f
diff --git a/AGENTS.md b/AGENTS.md
index a5e3633a..873ef10f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -119,6 +119,6 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
- 53 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all)
- 128 REST endpoints
- 6 MCP resources, 3 MCP prompts
-- 12 hooks, 4 skills
+- 12 hooks, 15 skills
- 50+ iii functions
- 950+ tests
diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.md
index b7df5656..981c3893 100644
--- a/INSTALL_FOR_AGENTS.md
+++ b/INSTALL_FOR_AGENTS.md
@@ -128,7 +128,7 @@ These are off by default because they spend tokens. Enable them only if the user
## Tool surface
-The MCP server exposes 53 tools by default (`--tools all`). Use `--tools core` (or `AGENTMEMORY_TOOLS=core`) for a lean 8-tool set on hosts with tight tool limits. The 8 core tools cover save, recall, smart search, sessions, export, audit, and governance delete.
+The MCP server exposes 53 tools by default (`--tools all`). Use `--tools core` (or `AGENTMEMORY_TOOLS=core`) for a lean 8-tool set on hosts with tight tool limits. The 8 core tools cover save, recall, consolidate, smart search, sessions, diagnose, lesson save, and reflect.
## Lifecycle commands
diff --git a/plugin/skills/agentmemory-agents/REFERENCE.md b/plugin/skills/agentmemory-agents/REFERENCE.md
index 1dd0b7a2..d1d82950 100644
--- a/plugin/skills/agentmemory-agents/REFERENCE.md
+++ b/plugin/skills/agentmemory-agents/REFERENCE.md
@@ -8,7 +8,7 @@ Generated from `src/cli/connect/index.ts`. Do not edit the block below by hand;
| 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. |
+| Claude Code | `claude-code` | Using MCP. Hooks are also available, see https://github.com/rohitg00/agentmemory#claude-code-one-block-paste-it. |
| 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). |
@@ -16,9 +16,9 @@ Generated from `src/cli/connect/index.ts`. Do not edit the block below by hand;
| 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. |
+| Hermes Agent | `hermes` | Using MCP. Hooks are also available, see https://github.com/rohitg00/agentmemory/tree/main/integrations/hermes. |
| 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. |
+| OpenClaw | `openclaw` | Using MCP. Hooks are also available, see https://github.com/rohitg00/agentmemory/tree/main/integrations/openclaw. |
| OpenCode | `opencode` | Using MCP via ~/.config/opencode/opencode.json (top-level `mcp` key). For full auto-capture, also install the bundled plugin in plugin/opencode/. |
| OpenHuman | `openhuman` | Using native hooks (REST API at :3111). MCP not required. |
| pi | `pi` | Using native hooks (REST API at :3111). MCP not required. |
diff --git a/src/cli.ts b/src/cli.ts
index ae5be003..48f6f09b 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -44,6 +44,7 @@ import { runOnboarding } from "./cli/onboarding.js";
import { setBootVerbose } from "./logger.js";
import { VERSION } from "./version.js";
import { getAllTools, ESSENTIAL_TOOLS } from "./mcp/tools-registry.js";
+import { knownAgents } from "./cli/connect/index.js";
const ALL_TOOLS_COUNT = getAllTools().length;
const CORE_TOOLS_COUNT = getAllTools().filter((t) => ESSENTIAL_TOOLS.has(t.name)).length;
@@ -120,6 +121,22 @@ function vlog(msg: string): void {
if (IS_VERBOSE) p.log.info(`[verbose] ${msg}`);
}
+function wrapList(items: readonly string[], indent: number, width = 78): string {
+ const lines: string[] = [];
+ let line = "";
+ for (const item of items) {
+ const joined = line ? `${line}, ${item}` : item;
+ if (line && indent + joined.length > width) {
+ lines.push(`${line},`);
+ line = item;
+ } else {
+ line = joined;
+ }
+ }
+ lines.push(line);
+ return lines.join(`\n${" ".repeat(indent)}`);
+}
+
if (args.includes("--help") || args.includes("-h")) {
console.log(`
agentmemory — persistent memory for AI coding agents
@@ -129,9 +146,8 @@ Usage: agentmemory [command] [options]
Commands:
(default) Start agentmemory worker
init Copy bundled .env.example to ~/.agentmemory/.env if absent
- connect [agent] Wire agentmemory into an installed agent (claude-code,
- copilot-cli, codex, cursor, gemini-cli, openclaw,
- hermes, pi, openhuman).
+ connect [agent] Wire agentmemory into an installed agent
+ (${wrapList(knownAgents(), 21)}).
No arg = interactive picker. --all wires every detected agent.
--dry-run shows what would change. --force re-installs.
status Show connection status, memory count, flags, and health
@@ -191,7 +207,13 @@ Quick start:
const toolsIdx = args.indexOf("--tools");
if (toolsIdx !== -1 && args[toolsIdx + 1]) {
- process.env["AGENTMEMORY_TOOLS"] = args[toolsIdx + 1];
+ const toolsMode = args[toolsIdx + 1]!;
+ if (toolsMode !== "all" && toolsMode !== "core") {
+ p.log.warn(
+ `Unknown --tools value "${toolsMode}" (valid: all, core); falling back to all.`,
+ );
+ }
+ process.env["AGENTMEMORY_TOOLS"] = toolsMode;
}
const portIdx = args.indexOf("--port");
diff --git a/src/cli/connect/claude-code.ts b/src/cli/connect/claude-code.ts
index 8fcb2cca..6d9ef067 100644
--- a/src/cli/connect/claude-code.ts
+++ b/src/cli/connect/claude-code.ts
@@ -42,7 +42,7 @@ export const adapter: ConnectAdapter = {
category: "native",
docs: "https://github.com/rohitg00/agentmemory#claude-code-one-block-paste-it",
protocolNote:
- "→ Using MCP. Hooks are also available — see docs/claude-code.md.",
+ "→ Using MCP. Hooks are also available — see https://github.com/rohitg00/agentmemory#claude-code-one-block-paste-it.",
detect(): boolean {
return existsSync(CLAUDE_DIR);
diff --git a/src/cli/connect/hermes.ts b/src/cli/connect/hermes.ts
index a9e15b8a..9720472b 100644
--- a/src/cli/connect/hermes.ts
+++ b/src/cli/connect/hermes.ts
@@ -14,7 +14,7 @@ export const adapter: ConnectAdapter = {
category: "native",
docs: DOCS,
protocolNote:
- "→ Using MCP. Hooks are also available — see docs/hermes.md.",
+ "→ Using MCP. Hooks are also available — see https://github.com/rohitg00/agentmemory/tree/main/integrations/hermes.",
detect(): boolean {
return existsSync(HERMES_DIR);
diff --git a/src/cli/connect/index.ts b/src/cli/connect/index.ts
index ccf0553e..6512c5bd 100644
--- a/src/cli/connect/index.ts
+++ b/src/cli/connect/index.ts
@@ -200,7 +200,7 @@ function summarize(
);
if (wiredAny) {
p.log.info(
- "Next: install agentmemory's 8 skills into the same agent(s) so they know when to call the tools:\n npx skills add rohitg00/agentmemory -y",
+ "Next: install agentmemory's 15 skills into the same agent(s) so they know when to call the tools:\n npx skills add rohitg00/agentmemory -y",
);
}
diff --git a/src/cli/connect/openclaw.ts b/src/cli/connect/openclaw.ts
index 66b69b0a..837e1f25 100644
--- a/src/cli/connect/openclaw.ts
+++ b/src/cli/connect/openclaw.ts
@@ -10,5 +10,5 @@ export const adapter = createJsonMcpAdapter({
configPath: join(homedir(), ".openclaw", "openclaw.json"),
docs: "https://github.com/rohitg00/agentmemory/tree/main/integrations/openclaw",
protocolNote:
- "→ Using MCP. Hooks are also available — see docs/openclaw.md.",
+ "→ Using MCP. Hooks are also available — see https://github.com/rohitg00/agentmemory/tree/main/integrations/openclaw.",
});
diff --git a/test/tool-count-consistency.test.ts b/test/tool-count-consistency.test.ts
index 19f0e3a5..6e845df0 100644
--- a/test/tool-count-consistency.test.ts
+++ b/test/tool-count-consistency.test.ts
@@ -1,5 +1,5 @@
import { describe, it, expect, vi } from "vitest";
-import { readFileSync } from "node:fs";
+import { readdirSync, readFileSync } from "node:fs";
import { join } from "node:path";
vi.mock("../src/logger.js", () => ({
@@ -40,4 +40,24 @@ describe("Tool count consistency", () => {
expect(readme).toContain(`${EXPECTED_TOOL_COUNT} MCP tools`);
expect(readme).not.toContain("51 MCP tools");
});
+
+ it("skill count claims match the plugin/skills directory", () => {
+ const skillCount = readdirSync(join(ROOT, "plugin", "skills"), {
+ withFileTypes: true,
+ }).filter((e) => e.isDirectory() && e.name !== "_shared").length;
+ expect(readText("src/cli/connect/index.ts")).toContain(`${skillCount} skills`);
+ expect(readText("README.md")).toContain(`${skillCount} skills`);
+ expect(readText("AGENTS.md")).toContain(`12 hooks, ${skillCount} skills`);
+ expect(readText("plugin/plugin.json")).toContain(`${skillCount} skills`);
+ });
+
+ it("INSTALL_FOR_AGENTS.md names the real core tool set", () => {
+ const names = [...ESSENTIAL_TOOLS].map((t) =>
+ t.replace(/^memory_/, "").replace(/_/g, " "),
+ );
+ const sentence = `The ${names.length} core tools cover ${names
+ .slice(0, -1)
+ .join(", ")}, and ${names[names.length - 1]}.`;
+ expect(readText("INSTALL_FOR_AGENTS.md")).toContain(sentence);
+ });
});