feat: wire agent memory integrations

Author: ElhamDevelopmentStudio

README.md

@@ -17,7 +17,7 @@ This README is only for setting up Kairo as a user.
 ## Install
 
 ```sh
-npm install -g @kairohq/cli
+npm install -g @kairohq/cli @kairohq/mcp
 ```
 
 ## Initialize A Project
@@ -28,8 +28,9 @@ Run this inside the project you want Kairo to remember.
 kairo init
 ```
 
-Guided setup can import supported local assistant transcripts and configure an
-optional AI provider. You can skip both and still use local project memory.
+`kairo init` creates local Kairo state, installs Claude Code and Codex capture
+hooks, and registers the local Kairo MCP server so those assistants can query
+project memory. No Kairo AI provider is required by default.
 
 ## Ingest Existing History
 
@@ -51,14 +52,8 @@ kairo doctor
 kairo ask "what changed in the dashboard data source?"
 ```
 
-## Optional MCP Server
-
-Install this only when an MCP-compatible assistant should query Kairo memory.
-
-```sh
-npm install -g @kairohq/mcp
-kairo-mcp
-```
+Claude Code and Codex can also ask Kairo through the MCP setup written by
+`kairo init`.
 
 ## Where To Read More
 

apps/cli/src/commands/doctor.test.ts

@@ -35,6 +35,10 @@ describe("runDoctor", () => {
       { label: ".git directory", ok: true },
       { label: "Claude Code hook", ok: true },
       { label: "Codex hook", ok: true },
+      { label: "Kairo MCP config", ok: true },
+      { label: "Codex MCP config", ok: true },
+      { label: "Agent memory guidance", ok: true },
+      { label: "Claude memory guidance", ok: true },
     ]);
     expect(result.gateways.map((gateway) => [gateway.name, gateway.readiness])).toEqual([
       ["codex", "ready"],

apps/cli/src/commands/doctor.ts

@@ -44,6 +44,10 @@ export async function runDoctor(
       { label: ".git directory", ok: existsSync(join(cwd, ".git")) },
       { label: "Claude Code hook", ok: existsSync(join(cwd, ".claude/hooks.json")) },
       { label: "Codex hook", ok: existsSync(join(cwd, ".codex/hooks.json")) },
+      { label: "Kairo MCP config", ok: existsSync(join(cwd, ".mcp.json")) },
+      { label: "Codex MCP config", ok: existsSync(join(cwd, ".codex/config.toml")) },
+      { label: "Agent memory guidance", ok: existsSync(join(cwd, "AGENTS.md")) },
+      { label: "Claude memory guidance", ok: existsSync(join(cwd, "CLAUDE.md")) },
     ],
     gateways,
   };

apps/cli/src/commands/init.test.ts

@@ -19,8 +19,14 @@ describe("runInit", () => {
     const first = runInit({ name: "demo" }, projectRoot);
     const claudePath = join(projectRoot, ".claude", "hooks.json");
     const codexPath = join(projectRoot, ".codex", "hooks.json");
+    const mcpPath = join(projectRoot, ".mcp.json");
+    const agentsPath = join(projectRoot, "AGENTS.md");
+    const claudeGuidePath = join(projectRoot, "CLAUDE.md");
     const firstClaude = readFileSync(claudePath, "utf8");
     const firstCodex = readFileSync(codexPath, "utf8");
+    const firstMcp = readFileSync(mcpPath, "utf8");
+    const firstAgents = readFileSync(agentsPath, "utf8");
+    const firstClaudeGuide = readFileSync(claudeGuidePath, "utf8");
 
     const second = runInit({ name: "ignored" }, projectRoot);
 
@@ -35,19 +41,19 @@ describe("runInit", () => {
     });
     expect(readFileSync(claudePath, "utf8")).toBe(firstClaude);
     expect(readFileSync(codexPath, "utf8")).toBe(firstCodex);
+    expect(readFileSync(mcpPath, "utf8")).toBe(firstMcp);
+    expect(readFileSync(agentsPath, "utf8")).toBe(firstAgents);
+    expect(readFileSync(claudeGuidePath, "utf8")).toBe(firstClaudeGuide);
+    expect(JSON.parse(firstMcp).mcpServers.kairo.command).toBe("kairo-mcp");
+    expect(firstAgents).toContain("Kairo Project Memory");
+    expect(firstClaudeGuide).toContain("Kairo Project Memory");
   });
 
-  it("writes MiniMax AI config by default", () => {
+  it("uses local memory without AI by default", () => {
     runInit({ name: "demo" }, projectRoot);
     const config = JSON.parse(readFileSync(join(projectRoot, ".kairo", "config.json"), "utf8"));
 
-    expect(config.ai).toEqual({
-      provider: "minimax",
-      model: "MiniMax-M2.7",
-      apiKeyEnv: "MINIMAX_API_KEY",
-      authMode: "api-key",
-      baseUrl: "https://api.minimax.io/v1",
-    });
+    expect(config.ai).toBeNull();
     expect(config.agentIngest).toEqual({ enabled: false, providers: [] });
   });
 

apps/cli/src/commands/init.ts

@@ -180,7 +180,7 @@ async function withOnboarding(opts: InitOptions): Promise<InitOptions> {
     const wantsProvider = await confirm(
       readline,
       "Use an AI provider for natural-language answers and summaries?",
-      true,
+      false,
     );
     if (!wantsProvider) return { ...opts, agentProviders, aiProvider: "none" };
 
@@ -209,7 +209,7 @@ function agentIngestConfigFromOptions(agentProviders: string | undefined) {
 }
 
 function aiConfigFromOptions(
-  providerChoice = "minimax",
+  providerChoice = "none",
   authChoice?: string,
   apiKeyEnvChoice?: string,
 ): WorkspaceAiConfigType | null {

apps/mcp/src/tools/ask.test.ts

@@ -36,12 +36,7 @@ describe("askProjectMemory", () => {
       store.close();
     }
 
-    const answer = await askProjectMemory(
-      { workspace },
-      "Why did dashboard routing change?",
-      5,
-      false,
-    );
+    const answer = await askProjectMemory({ workspace }, "Why did dashboard routing change?", 5);
 
     expect(answer?.answer).toContain("Dashboard routing split");
     expect(answer?.citations[0]).toMatchObject({

apps/mcp/src/tools/ask.ts

@@ -9,7 +9,7 @@ export async function askProjectMemory(
   context: ToolContext,
   question: string,
   limit: number,
-  useAi = true,
+  useAi = false,
 ): Promise<MemoryAnswer | null> {
   const trimmed = question.trim();
   if (!context.workspace || trimmed.length === 0) return null;
@@ -40,7 +40,7 @@ export function registerAskTool(server: McpServer, context: ToolContext): void {
     {
       question: z.string(),
       limit: z.number().int().positive().max(10).default(5),
-      useAi: z.boolean().default(true),
+      useAi: z.boolean().default(false),
     },
     async ({ question, limit, useAi }) => ({
       content: [

packages/core/src/hooks/merge-hooks.test.ts

@@ -5,7 +5,11 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
   installKairoHooks,
   mergeKairoHooks,
+  mergeKairoMcpConfig,
+  mergeManagedText,
   removeKairoHooks,
+  removeKairoMcpConfig,
+  removeManagedText,
   uninstallKairoHooks,
 } from "./merge-hooks.ts";
 
@@ -103,18 +107,70 @@ describe("mergeKairoHooks", () => {
   });
 });
 
+describe("mergeKairoMcpConfig", () => {
+  it("preserves existing MCP servers and installs Kairo", () => {
+    expect(
+      mergeKairoMcpConfig(
+        { mcpServers: { custom: { command: "custom-mcp" } } },
+        { mcpServers: { kairo: { command: "kairo-mcp", args: [], enabled: true } } },
+      ),
+    ).toEqual({
+      mcpServers: {
+        custom: { command: "custom-mcp" },
+        kairo: { command: "kairo-mcp", args: [], enabled: true },
+      },
+    });
+  });
+});
+
+describe("managed text sections", () => {
+  const marker = {
+    start: "<!-- KAIRO:TEST:START -->",
+    end: "<!-- KAIRO:TEST:END -->",
+  };
+  const template = "<!-- KAIRO:TEST:START -->\nmanaged\n<!-- KAIRO:TEST:END -->\n";
+
+  it("appends and refreshes one managed section", () => {
+    const once = mergeManagedText("# Existing\n", template, marker);
+    const twice = mergeManagedText(once, template.replace("managed", "refreshed"), marker);
+
+    expect(once).toContain("# Existing");
+    expect(twice.match(/KAIRO:TEST:START/g)).toHaveLength(1);
+    expect(twice).toContain("refreshed");
+    expect(twice).not.toContain("managed\n");
+  });
+
+  it("removes only the managed section", () => {
+    const merged = mergeManagedText("# Existing\n", template, marker);
+
+    expect(removeManagedText(merged, marker)).toBe("# Existing");
+  });
+});
+
 describe("installKairoHooks", () => {
-  it("reads templates from disk and writes idempotent Claude and Codex hook files", () => {
+  it("reads templates from disk and writes idempotent agent integration files", () => {
     installKairoHooks(projectRoot);
     const claudePath = join(projectRoot, ".claude", "hooks.json");
     const codexPath = join(projectRoot, ".codex", "hooks.json");
+    const mcpPath = join(projectRoot, ".mcp.json");
+    const codexConfigPath = join(projectRoot, ".codex", "config.toml");
+    const agentsPath = join(projectRoot, "AGENTS.md");
+    const claudeGuidePath = join(projectRoot, "CLAUDE.md");
     const firstClaude = readFileSync(claudePath, "utf8");
     const firstCodex = readFileSync(codexPath, "utf8");
+    const firstMcp = readFileSync(mcpPath, "utf8");
+    const firstCodexConfig = readFileSync(codexConfigPath, "utf8");
+    const firstAgents = readFileSync(agentsPath, "utf8");
+    const firstClaudeGuide = readFileSync(claudeGuidePath, "utf8");
 
     installKairoHooks(projectRoot);
 
     expect(readFileSync(claudePath, "utf8")).toBe(firstClaude);
     expect(readFileSync(codexPath, "utf8")).toBe(firstCodex);
+    expect(readFileSync(mcpPath, "utf8")).toBe(firstMcp);
+    expect(readFileSync(codexConfigPath, "utf8")).toBe(firstCodexConfig);
+    expect(readFileSync(agentsPath, "utf8")).toBe(firstAgents);
+    expect(readFileSync(claudeGuidePath, "utf8")).toBe(firstClaudeGuide);
     const claude = JSON.parse(firstClaude);
     expect(claude.hooks.PostToolUse[0].kairo).toBe(true);
     expect(claude.hooks.PreCompact[0]).toMatchObject({
@@ -126,6 +182,13 @@ describe("installKairoHooks", () => {
       hooks: [{ command: "kairo wake --days 7" }],
     });
     expect(JSON.parse(firstCodex).hooks[0].kairo).toBe(true);
+    expect(JSON.parse(firstMcp).mcpServers.kairo).toMatchObject({
+      command: "kairo-mcp",
+      enabled: true,
+    });
+    expect(firstCodexConfig).toContain("[mcp_servers.kairo]");
+    expect(firstAgents).toContain("Kairo Project Memory");
+    expect(firstClaudeGuide).toContain("Kairo Project Memory");
   });
 
   it("preserves pre-existing non-Kairo hooks when installing", () => {
@@ -151,6 +214,23 @@ describe("installKairoHooks", () => {
   });
 });
 
+describe("removeKairoMcpConfig", () => {
+  it("removes only the Kairo MCP server", () => {
+    expect(
+      removeKairoMcpConfig({
+        mcpServers: {
+          custom: { command: "custom" },
+          kairo: { command: "kairo-mcp" },
+        },
+      }),
+    ).toEqual({
+      mcpServers: {
+        custom: { command: "custom" },
+      },
+    });
+  });
+});
+
 describe("removeKairoHooks", () => {
   it("removes only tagged Claude hooks", () => {
     expect(
@@ -194,15 +274,21 @@ describe("uninstallKairoHooks", () => {
     installKairoHooks(projectRoot);
     const claudePath = join(projectRoot, ".claude", "hooks.json");
     const codexPath = join(projectRoot, ".codex", "hooks.json");
+    const mcpPath = join(projectRoot, ".mcp.json");
+    const codexConfigPath = join(projectRoot, ".codex", "config.toml");
+    const agentsPath = join(projectRoot, "AGENTS.md");
     const claudeWithCustom = JSON.parse(readFileSync(claudePath, "utf8"));
     const codexWithCustom = JSON.parse(readFileSync(codexPath, "utf8"));
+    const mcpWithCustom = JSON.parse(readFileSync(mcpPath, "utf8"));
     claudeWithCustom.hooks.PostToolUse.unshift({
       matcher: "Write",
       hooks: [{ type: "command", command: "custom" }],
     });
     codexWithCustom.hooks.unshift({ event: "post_edit", command: "custom" });
+    mcpWithCustom.mcpServers.custom = { command: "custom" };
     writeFileSync(claudePath, JSON.stringify(claudeWithCustom));
     writeFileSync(codexPath, JSON.stringify(codexWithCustom));
+    writeFileSync(mcpPath, JSON.stringify(mcpWithCustom));
 
     uninstallKairoHooks(projectRoot);
 
@@ -212,5 +298,9 @@ describe("uninstallKairoHooks", () => {
     expect(JSON.stringify(codex)).toContain("custom");
     expect(JSON.stringify(claude)).not.toContain('"kairo":true');
     expect(JSON.stringify(codex)).not.toContain('"kairo":true');
+    expect(readFileSync(mcpPath, "utf8")).toContain("custom");
+    expect(readFileSync(mcpPath, "utf8")).not.toContain("kairo-mcp");
+    expect(readFileSync(codexConfigPath, "utf8")).not.toContain("[mcp_servers.kairo]");
+    expect(readFileSync(agentsPath, "utf8")).not.toContain("Kairo Project Memory");
   });
 });