Skip to content

fix: CLI help and docs papercuts #897

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.

Sign up for GitHub

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
rohitg00 merged 2 commits into from
Jun 10, 2026
Merged

fix: CLI help and docs papercuts #897

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b4fbebd
fix: CLI help and docs papercuts
rohitg00 Jun 10, 2026
b0595f3
chore: regenerate skill reference docs
rohitg00 Jun 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion INSTALL_FOR_AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 3 additions & 3 deletions plugin/skills/agentmemory-agents/REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,17 @@ 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). |
| 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. |
| 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. |
Expand Down
30 changes: 26 additions & 4 deletions src/cli.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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;
}
Comment on lines +211 to 217

@coderabbitai coderabbitai Bot Jun 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Normalize invalid --tools values before writing env.

At Line 216, invalid input is still persisted (AGENTMEMORY_TOOLS=<invalid>), even though Line 213 says fallback is all. Persist the normalized value instead.

Suggested fix 
 const toolsMode = args[toolsIdx + 1]!;
+const normalizedToolsMode =
+  toolsMode === "all" || toolsMode === "core" ? toolsMode : "all";
 if (toolsMode !== "all" && toolsMode !== "core") {
   p.log.warn(
     `Unknown --tools value "${toolsMode}" (valid: all, core); falling back to all.`,
   );
 }
-process.env["AGENTMEMORY_TOOLS"] = toolsMode;
+process.env["AGENTMEMORY_TOOLS"] = normalizedToolsMode;
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
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 normalizedToolsMode =
toolsMode === "all" || toolsMode === "core" ? toolsMode : "all";
if (toolsMode !== "all" && toolsMode !== "core") {
p.log.warn(
`Unknown --tools value "${toolsMode}" (valid: all, core); falling back to all.`,
);
}
process.env["AGENTMEMORY_TOOLS"] = normalizedToolsMode;
}
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli.ts` around lines 211 - 217, The code warns on invalid toolsMode but
still persists the original value; update the branch that checks toolsMode (the
if block referencing toolsMode !== "all" && toolsMode !== "core") to normalize
the value before writing the env: set toolsMode = "all" (or desired fallback)
inside that block and then assign process.env["AGENTMEMORY_TOOLS"] = toolsMode
so the normalized value is persisted; ensure the p.log.warn message remains
informative and uses the normalized value if needed.


const portIdx = args.indexOf("--port");
Expand Down
2 changes: 1 addition & 1 deletion src/cli/connect/claude-code.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
2 changes: 1 addition & 1 deletion src/cli/connect/hermes.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
2 changes: 1 addition & 1 deletion src/cli/connect/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
);
}

Expand Down
2 changes: 1 addition & 1 deletion src/cli/connect/openclaw.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.",
});
22 changes: 21 additions & 1 deletion test/tool-count-consistency.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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", () => ({
Expand Down Expand Up @@ -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);
});
});