Skip to content

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

feat(cli): clarify MCP is opt-in — REST primary, MCP for MCP-only clients (#409)

Rohit Ghumare6e3c0529439c
diff --git a/src/cli.ts b/src/cli.ts
index 83baedba..803c3b6d 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -133,7 +133,8 @@ Commands:
--force bypasses the Docker-heuristic guard and signals
whatever pidfile+lsof report on the REST port (use when
the engine was started natively but state file is missing).
- mcp Start standalone MCP server (no engine required)
+ mcp Start standalone MCP shim — opt-in surface for MCP-only clients
+ (Cursor, Gemini CLI, etc). REST always available at :3111.
import-jsonl [p] Import Claude Code JSONL transcripts (default: ~/.claude/projects)
--max-files <N> | --max-files=<N>: override scan cap (default 200, max 1000;
out-of-range is rejected; for trees >1000 files, batch by subdirectory)
diff --git a/src/cli/connect/claude-code.ts b/src/cli/connect/claude-code.ts
index 48117b93..9f196e7c 100644
--- a/src/cli/connect/claude-code.ts
+++ b/src/cli/connect/claude-code.ts
@@ -34,6 +34,8 @@ export const adapter: ConnectAdapter = {
name: "claude-code",
displayName: "Claude Code",
docs: "https://github.com/rohitg00/agentmemory#claude-code-one-block-paste-it",
+ protocolNote:
+ "→ Using MCP. Hooks are also available — see docs/claude-code.md.",
detect(): boolean {
return existsSync(CLAUDE_DIR);
diff --git a/src/cli/connect/codex.ts b/src/cli/connect/codex.ts
index b7d3b1fe..003dc99a 100644
--- a/src/cli/connect/codex.ts
+++ b/src/cli/connect/codex.ts
@@ -56,6 +56,8 @@ export const adapter: ConnectAdapter = {
name: "codex",
displayName: "Codex CLI",
docs: "https://github.com/rohitg00/agentmemory#codex-cli-codex-plugin-platform",
+ protocolNote:
+ "→ Using MCP. Hooks are also available — see docs/codex.md.",
detect(): boolean {
return existsSync(CODEX_DIR);
diff --git a/src/cli/connect/cursor.ts b/src/cli/connect/cursor.ts
index 7da7c7d7..fb4c5afb 100644
--- a/src/cli/connect/cursor.ts
+++ b/src/cli/connect/cursor.ts
@@ -8,4 +8,6 @@ export const adapter = createJsonMcpAdapter({
detectDir: join(homedir(), ".cursor"),
configPath: join(homedir(), ".cursor", "mcp.json"),
docs: "https://github.com/rohitg00/agentmemory#other-agents",
+ protocolNote:
+ "→ Using MCP (the only protocol Cursor speaks). Memory bridge runs at :3111 underneath.",
});
diff --git a/src/cli/connect/gemini-cli.ts b/src/cli/connect/gemini-cli.ts
index 1a38d608..6142a399 100644
--- a/src/cli/connect/gemini-cli.ts
+++ b/src/cli/connect/gemini-cli.ts
@@ -8,4 +8,6 @@ export const adapter = createJsonMcpAdapter({
detectDir: join(homedir(), ".gemini"),
configPath: join(homedir(), ".gemini", "settings.json"),
docs: "https://github.com/rohitg00/agentmemory#other-agents",
+ protocolNote:
+ "→ Using MCP (the only protocol Gemini CLI speaks). Memory bridge runs at :3111 underneath.",
});
diff --git a/src/cli/connect/hermes.ts b/src/cli/connect/hermes.ts
index 18d304fb..578e2a23 100644
--- a/src/cli/connect/hermes.ts
+++ b/src/cli/connect/hermes.ts
@@ -12,6 +12,8 @@ export const adapter: ConnectAdapter = {
name: "hermes",
displayName: "Hermes Agent",
docs: DOCS,
+ protocolNote:
+ "→ Using MCP. Hooks are also available — see docs/hermes.md.",
detect(): boolean {
return existsSync(HERMES_DIR);
diff --git a/src/cli/connect/index.ts b/src/cli/connect/index.ts
index 5d90a350..8a13d328 100644
--- a/src/cli/connect/index.ts
+++ b/src/cli/connect/index.ts
@@ -60,6 +60,9 @@ async function runAdapter(
return { kind: "skipped", reason: "not-detected" };
}
p.log.step(`Wiring ${adapter.displayName}…`);
+ if (adapter.protocolNote) {
+ p.log.message(adapter.protocolNote);
+ }
try {
return await adapter.install(opts);
} catch (err) {
diff --git a/src/cli/connect/json-mcp-adapter.ts b/src/cli/connect/json-mcp-adapter.ts
index b368805b..d72eb45c 100644
--- a/src/cli/connect/json-mcp-adapter.ts
+++ b/src/cli/connect/json-mcp-adapter.ts
@@ -18,6 +18,7 @@ export type JsonMcpAdapterConfig = {
detectDir: string;
configPath: string;
docs?: string;
+ protocolNote?: string;
};
type McpEntry = typeof AGENTMEMORY_MCP_BLOCK;
@@ -41,6 +42,9 @@ export function createJsonMcpAdapter(
name: config.name,
displayName: config.displayName,
...(config.docs !== undefined && { docs: config.docs }),
+ ...(config.protocolNote !== undefined && {
+ protocolNote: config.protocolNote,
+ }),
detect(): boolean {
return existsSync(config.detectDir);
diff --git a/src/cli/connect/openclaw.ts b/src/cli/connect/openclaw.ts
index b333920e..e417e267 100644
--- a/src/cli/connect/openclaw.ts
+++ b/src/cli/connect/openclaw.ts
@@ -8,4 +8,6 @@ export const adapter = createJsonMcpAdapter({
detectDir: join(homedir(), ".openclaw"),
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.",
});
diff --git a/src/cli/connect/openhuman.ts b/src/cli/connect/openhuman.ts
index bcbfbbbc..108b8117 100644
--- a/src/cli/connect/openhuman.ts
+++ b/src/cli/connect/openhuman.ts
@@ -11,6 +11,8 @@ export const adapter: ConnectAdapter = {
name: "openhuman",
displayName: "OpenHuman",
docs: DOCS,
+ protocolNote:
+ "→ Using native hooks (REST API at :3111). MCP not required.",
detect(): boolean {
return existsSync(OPENHUMAN_DIR);
diff --git a/src/cli/connect/pi.ts b/src/cli/connect/pi.ts
index b6552a90..669d8127 100644
--- a/src/cli/connect/pi.ts
+++ b/src/cli/connect/pi.ts
@@ -12,6 +12,8 @@ export const adapter: ConnectAdapter = {
name: "pi",
displayName: "pi",
docs: DOCS,
+ protocolNote:
+ "→ Using native hooks (REST API at :3111). MCP not required.",
detect(): boolean {
return existsSync(PI_DIR);
diff --git a/src/cli/connect/types.ts b/src/cli/connect/types.ts
index adfaef30..4f64c867 100644
--- a/src/cli/connect/types.ts
+++ b/src/cli/connect/types.ts
@@ -7,6 +7,13 @@ export type ConnectAdapter = {
name: string;
displayName: string;
docs?: string;
+ /**
+ * One-line explanation of which protocol this adapter wires (REST hooks vs
+ * MCP) and why. Printed above the install summary so users see — before
+ * any config mutation — that REST is the primary surface and MCP is the
+ * opt-in bridge for MCP-only clients.
+ */
+ protocolNote?: string;
detect(): boolean;
install(opts: ConnectOptions): Promise<ConnectResult>;
};
diff --git a/src/index.ts b/src/index.ts
index 3a4db0e7..c662643f 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -461,7 +461,10 @@ async function main() {
`Ready. ${embeddingProvider ? "Triple-stream (BM25+Vector+Graph)" : "BM25+Graph"} search active.`,
);
bootLog(
- `Endpoints: 107 REST + ${getAllTools().length} MCP tools + 6 MCP resources + 3 MCP prompts`,
+ `REST API: 107 endpoints at http://localhost:${config.restPort}/agentmemory/*`,
+ );
+ bootLog(
+ `MCP surface (opt-in via \`npx @agentmemory/mcp\`): ${getAllTools().length} tools · 6 resources · 3 prompts`,
);
const viewerPort = config.restPort + 2;