@nogataka/claw-memory 0.1.0

package/dist/core/embeddings.js

@@ -0,0 +1,34 @@
+// src/core/embeddings.ts
+//
+// Fully local embeddings via Xenova Transformers.js (multilingual-e5-small,
+// 384-dim). No API, no network at inference time, multilingual (Japanese OK).
+/* eslint-disable @typescript-eslint/no-explicit-any */
+let pipelineInstance = null;
+let loadingPromise = null;
+async function getEmbeddingPipeline() {
+    if (pipelineInstance)
+        return pipelineInstance;
+    if (loadingPromise)
+        return loadingPromise;
+    loadingPromise = (async () => {
+        const { pipeline } = await import("@xenova/transformers");
+        pipelineInstance = await pipeline("feature-extraction", "Xenova/multilingual-e5-small");
+        return pipelineInstance;
+    })();
+    pipelineInstance = await loadingPromise;
+    loadingPromise = null;
+    return pipelineInstance;
+}
+async function embed(text) {
+    const extractor = await getEmbeddingPipeline();
+    const output = await extractor(text, { pooling: "mean", normalize: true });
+    return new Float32Array(output.data);
+}
+/** Embed text for storage. e5 requires the "passage: " prefix. */
+export async function embedPassage(text) {
+    return embed(`passage: ${text}`);
+}
+/** Embed text for search. e5 requires the "query: " prefix. */
+export async function embedQuery(text) {
+    return embed(`query: ${text}`);
+}

package/dist/core/excludes.js

@@ -0,0 +1,16 @@
+// src/core/excludes.ts
+//
+// Project exclusion: paths matching CLAW_MEMORY_EXCLUDED_PROJECTS (comma or
+// path-separator separated substrings) are never recorded or recalled.
+function patterns() {
+    const raw = process.env.CLAW_MEMORY_EXCLUDED_PROJECTS ?? "";
+    return raw
+        .split(/[,:]/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+export function isExcludedPath(cwd) {
+    if (!cwd)
+        return false;
+    return patterns().some((p) => cwd.includes(p));
+}

package/dist/core/hooks.js

@@ -0,0 +1,76 @@
+// src/core/hooks.ts
+//
+// Claude Code lifecycle-hook handlers. Spawned per event (no daemon):
+//   - Stop / SessionEnd     → runDistillHook  (auto-distill the finished session)
+//   - SessionStart / Prompt → runRecallHook   (inject memory block into context)
+// Hook input arrives as JSON on stdin; recall output goes to stdout.
+import { statSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { getOrCreateProjectByPath } from "./projects.js";
+import { buildMemoryBlock } from "./recall.js";
+import { shouldDistill } from "./watermark.js";
+import { isExcludedPath } from "./excludes.js";
+import { log } from "./logger.js";
+export async function readStdinJson() {
+    const chunks = [];
+    for await (const c of process.stdin)
+        chunks.push(c);
+    const raw = Buffer.concat(chunks).toString("utf-8").trim();
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+const CLI_PATH = fileURLToPath(new URL("../cli.js", import.meta.url));
+/**
+ * Stop / SessionEnd: distill the just-finished transcript. Detached and
+ * fire-and-forget so the user's session isn't blocked by the LLM call. The
+ * watermark is re-checked (and stamped) inside the spawned `distill --if-stale`.
+ */
+export function runDistillHook(input) {
+    const transcriptPath = input.transcript_path;
+    const cwd = input.cwd ?? process.cwd();
+    if (!transcriptPath || isExcludedPath(cwd))
+        return;
+    let mtimeMs = 0;
+    try {
+        mtimeMs = statSync(transcriptPath).mtimeMs;
+    }
+    catch {
+        return;
+    }
+    if (!shouldDistill(transcriptPath, mtimeMs))
+        return;
+    log("hook.distill.spawn", { cwd, session: input.session_id });
+    const child = spawn(process.execPath, [
+        CLI_PATH,
+        "distill",
+        "--path",
+        transcriptPath,
+        "--cwd",
+        cwd,
+        "--session",
+        input.session_id ?? transcriptPath,
+        "--if-stale",
+    ], { detached: true, stdio: "ignore" });
+    child.unref();
+}
+/**
+ * SessionStart / UserPromptSubmit: print the memory block to stdout. When the
+ * event carries the user's prompt it also pulls semantically similar past
+ * conversations; otherwise just preferences + recent summaries.
+ */
+export async function runRecallHook(input) {
+    const cwd = input.cwd ?? process.cwd();
+    if (isExcludedPath(cwd))
+        return;
+    const project = getOrCreateProjectByPath(cwd);
+    const block = await buildMemoryBlock(project.id, input.prompt ?? "", 5);
+    if (block.fullText.trim())
+        process.stdout.write(block.fullText + "\n");
+}

package/dist/core/installer/claude.js

@@ -0,0 +1,87 @@
+// src/core/installer/claude.ts
+//
+// Manual (non-plugin) Claude Code setup: merge the claw-memory MCP server and
+// the recall/distill hooks into ~/.claude/settings.json. Use this only if you
+// are NOT installing the Claude Code plugin (the plugin wires these up itself).
+// Idempotent and reversible; settings.json is backed up before writing.
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from "node:fs";
+const CLAUDE_DIR = join(homedir(), ".claude");
+const SETTINGS = join(CLAUDE_DIR, "settings.json");
+const HOOK_EVENTS = [
+    ["SessionStart", "hook recall", false],
+    ["UserPromptSubmit", "hook recall", false],
+    ["Stop", "hook distill", true],
+];
+/** Resolve how to invoke claw-memory: global binary or npx. */
+function invoker() {
+    try {
+        const found = execFileSync("command", ["-v", "claw-memory"], {
+            shell: "/bin/bash",
+            encoding: "utf-8",
+        }).trim().split("\n")[0];
+        if (found)
+            return { mcp: { command: found, args: ["mcp"] }, cli: "claw-memory" };
+    }
+    catch {
+        // not on PATH
+    }
+    return {
+        mcp: { command: "npx", args: ["-y", "@nogataka/claw-memory@latest", "mcp"] },
+        cli: "npx -y @nogataka/claw-memory@latest",
+    };
+}
+function read() {
+    if (!existsSync(SETTINGS))
+        return {};
+    try {
+        return JSON.parse(readFileSync(SETTINGS, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function isOurs(cmd) {
+    return cmd.includes("claw-memory") && cmd.includes("hook ");
+}
+function save(s) {
+    mkdirSync(CLAUDE_DIR, { recursive: true });
+    if (existsSync(SETTINGS))
+        copyFileSync(SETTINGS, SETTINGS + ".bak");
+    writeFileSync(SETTINGS, JSON.stringify(s, null, 2) + "\n");
+}
+export function installClaude() {
+    const { mcp, cli } = invoker();
+    const s = read();
+    s.mcpServers = { ...(s.mcpServers ?? {}), "claw-memory": mcp };
+    s.hooks = s.hooks ?? {};
+    for (const [event, sub, isAsync] of HOOK_EVENTS) {
+        const list = (s.hooks[event] ?? []).filter((g) => !g.hooks?.some((h) => isOurs(h.command)));
+        const entry = { hooks: [{ type: "command", command: `${cli} ${sub}`, async: isAsync }] };
+        list.push(entry);
+        s.hooks[event] = list;
+    }
+    save(s);
+    return [
+        `settings.json: mcpServers.claw-memory (${mcp.command})`,
+        "settings.json: SessionStart/UserPromptSubmit→recall, Stop→distill",
+    ];
+}
+export function uninstallClaude() {
+    const s = read();
+    if (s.mcpServers)
+        delete s.mcpServers["claw-memory"];
+    if (s.hooks) {
+        for (const event of Object.keys(s.hooks)) {
+            s.hooks[event] = s.hooks[event]
+                .map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !isOurs(h.command)) }))
+                .filter((g) => g.hooks.length > 0);
+            if (s.hooks[event].length === 0)
+                delete s.hooks[event];
+        }
+    }
+    save(s);
+    return ["settings.json: removed claw-memory mcp + hooks"];
+}

package/dist/core/installer/codex.js

@@ -0,0 +1,122 @@
+// src/core/installer/codex.ts
+//
+// Codex has no third-party plugin marketplace, so "installing" claw-memory means
+// idempotently editing ~/.codex config: register the MCP server in config.toml,
+// drop a memory-recall skill, and add an AGENTS.md instruction. All edits live
+// inside marker blocks so they can be cleanly removed and never clobber the
+// user's own settings. config.toml is backed up before writing.
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, rmSync, } from "node:fs";
+const CODEX_DIR = join(homedir(), ".codex");
+const CONFIG = join(CODEX_DIR, "config.toml");
+const AGENTS = join(CODEX_DIR, "AGENTS.md");
+const SKILL_DIR = join(CODEX_DIR, "skills", "memory-recall");
+const BEGIN = "# >>> claw-memory >>>";
+const END = "# <<< claw-memory <<<";
+const A_BEGIN = "<!-- >>> claw-memory >>> -->";
+const A_END = "<!-- <<< claw-memory <<< -->";
+/** TOML basic-string literal with escaping. */
+function tomlStr(s) {
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/** Prefer a globally installed `claw-memory`; otherwise run via npx. */
+function resolveCommand() {
+    try {
+        const found = execFileSync("command", ["-v", "claw-memory"], {
+            shell: "/bin/bash",
+            encoding: "utf-8",
+        }).trim();
+        if (found)
+            return { command: found.split("\n")[0], args: ["mcp"] };
+    }
+    catch {
+        // not on PATH
+    }
+    return { command: "npx", args: ["-y", "@nogataka/claw-memory@latest", "mcp"] };
+}
+/** Insert or replace the marker-delimited block in `content`. */
+function upsertBlock(content, begin, end, block) {
+    const b = content.indexOf(begin);
+    const e = content.indexOf(end);
+    if (b !== -1 && e !== -1 && e > b) {
+        return content.slice(0, b) + block + content.slice(e + end.length);
+    }
+    const sep = content && !content.endsWith("\n") ? "\n\n" : content ? "\n" : "";
+    return content + sep + block + "\n";
+}
+/** Remove the marker-delimited block (and a trailing blank line) if present. */
+function removeBlock(content, begin, end) {
+    const b = content.indexOf(begin);
+    const e = content.indexOf(end);
+    if (b === -1 || e === -1 || e < b)
+        return content;
+    let out = content.slice(0, b) + content.slice(e + end.length);
+    return out.replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "");
+}
+function skillSource() {
+    // dist/core/installer/codex.js -> package root /skills/memory-recall/SKILL.md
+    return fileURLToPath(new URL("../../../skills/memory-recall/SKILL.md", import.meta.url));
+}
+export function installCodex() {
+    const done = [];
+    mkdirSync(CODEX_DIR, { recursive: true });
+    // 1) MCP server registration in config.toml
+    const { command, args } = resolveCommand();
+    const block = [
+        BEGIN,
+        "[mcp_servers.claw-memory]",
+        `command = ${tomlStr(command)}`,
+        `args = [${args.map(tomlStr).join(", ")}]`,
+        END,
+    ].join("\n");
+    const prev = existsSync(CONFIG) ? readFileSync(CONFIG, "utf-8") : "";
+    if (existsSync(CONFIG))
+        copyFileSync(CONFIG, CONFIG + ".bak");
+    writeFileSync(CONFIG, upsertBlock(prev, BEGIN, END, block));
+    done.push(`config.toml: [mcp_servers.claw-memory] (${command})`);
+    // 2) memory-recall skill
+    try {
+        mkdirSync(SKILL_DIR, { recursive: true });
+        copyFileSync(skillSource(), join(SKILL_DIR, "SKILL.md"));
+        done.push(`skill: ${SKILL_DIR}/SKILL.md`);
+    }
+    catch (e) {
+        done.push(`skill: SKIPPED (${String(e)})`);
+    }
+    // 3) AGENTS.md recall instruction
+    const agentsBlock = [
+        A_BEGIN,
+        "## claw-memory",
+        "",
+        "セッション冒頭で MCP ツール `memory_recall`（query=ユーザーの依頼）を呼び、過去の好み・要約・類似会話を取得すること。",
+        "特定の話題を探すときは `memory_search`、過去の生ログ（Claude Code/Codex）は `memory_search_logs` を使う。",
+        A_END,
+    ].join("\n");
+    const agentsPrev = existsSync(AGENTS) ? readFileSync(AGENTS, "utf-8") : "";
+    writeFileSync(AGENTS, upsertBlock(agentsPrev, A_BEGIN, A_END, agentsBlock));
+    done.push("AGENTS.md: recall instruction");
+    return done;
+}
+export function uninstallCodex() {
+    const done = [];
+    if (existsSync(CONFIG)) {
+        copyFileSync(CONFIG, CONFIG + ".bak");
+        writeFileSync(CONFIG, removeBlock(readFileSync(CONFIG, "utf-8"), BEGIN, END));
+        done.push("config.toml: removed claw-memory block");
+    }
+    if (existsSync(AGENTS)) {
+        writeFileSync(AGENTS, removeBlock(readFileSync(AGENTS, "utf-8"), A_BEGIN, A_END));
+        done.push("AGENTS.md: removed claw-memory block");
+    }
+    try {
+        rmSync(SKILL_DIR, { recursive: true, force: true });
+        done.push("skill: removed");
+    }
+    catch {
+        // ignore
+    }
+    return done;
+}

package/dist/core/llm.js

@@ -0,0 +1,163 @@
+// src/core/llm.ts
+//
+// Pluggable single-turn LLM completion. distill() only ever needs a tool-less
+// one-shot completion (maxTurns:1, allowedTools:[]), so the Claude Agent SDK is
+// not required — it is just one of several interchangeable backends here.
+//
+//   CLAW_MEMORY_LLM_BACKEND = agent-sdk (default) | codex-sdk | anthropic | openai-compatible
+//
+// - agent-sdk:        zero-config; reuses Claude Code CLI's stored credentials
+//                     (Claude Pro/Max/Team/Enterprise via the Agent SDK).
+// - codex-sdk:        reuses the Codex CLI's stored login (ChatGPT/Codex plan)
+//                     via @openai/codex-sdk — no API key. Requires Codex CLI.
+// - anthropic:        plain Messages API over fetch (needs ANTHROPIC_API_KEY).
+// - openai-compatible: OpenAI/Gemini/OpenRouter/LM Studio chat-completions.
+//
+// Tier routing lets cheap models handle simple work:
+//   CLAW_MEMORY_TIER_SMART / _SUMMARY / _SIMPLE  (model id per tier)
+// The two SDK backends reuse a subscription login; the HTTP backends need fetch
+// (built into Node >=20).
+import os from "node:os";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { buildFullSdkEnv } from "./providers.js";
+export function getBackend() {
+    return process.env.CLAW_MEMORY_LLM_BACKEND ?? "agent-sdk";
+}
+/**
+ * Resolve the env-configured model id for a tier, or undefined when unset.
+ * Each backend applies its own default when this is undefined.
+ */
+export function modelForTier(tier) {
+    const def = process.env.AGENT_SDK_MODEL ?? process.env.CLAW_MEMORY_MODEL;
+    switch (tier) {
+        case "simple":
+            return process.env.CLAW_MEMORY_TIER_SIMPLE ?? def;
+        case "summary":
+            return process.env.CLAW_MEMORY_TIER_SUMMARY ?? def;
+        case "smart":
+            return process.env.CLAW_MEMORY_TIER_SMART ?? def;
+    }
+}
+export async function complete(opts) {
+    const tier = opts.tier ?? "summary";
+    const model = modelForTier(tier);
+    const backend = getBackend();
+    switch (backend) {
+        case "agent-sdk":
+            return completeAgentSdk(opts.prompt, model ?? "claude-sonnet-4-5");
+        case "codex-sdk":
+            return completeCodexSdk(opts.prompt, model);
+        case "anthropic":
+            return completeAnthropic(opts.prompt, model ?? "claude-sonnet-4-5", opts.maxTokens);
+        case "openai-compatible":
+            return completeOpenAi(opts.prompt, model, opts.maxTokens);
+        default:
+            throw new Error(`unknown CLAW_MEMORY_LLM_BACKEND: ${backend} (expected agent-sdk|codex-sdk|anthropic|openai-compatible)`);
+    }
+}
+async function completeAgentSdk(prompt, model) {
+    const sdkStream = query({
+        prompt,
+        options: {
+            model,
+            maxTurns: 1,
+            allowedTools: [],
+            permissionMode: "bypassPermissions",
+            env: buildFullSdkEnv(),
+        },
+    });
+    let text = "";
+    for await (const event of sdkStream) {
+        const ev = event;
+        if (ev.type === "assistant" && ev.message?.role === "assistant") {
+            const content = ev.message.content;
+            if (typeof content === "string")
+                text += content;
+            else if (Array.isArray(content)) {
+                for (const block of content) {
+                    const b = block;
+                    if (b.type === "text" && b.text)
+                        text += b.text;
+                }
+            }
+        }
+    }
+    return text;
+}
+async function completeCodexSdk(prompt, model) {
+    // Dynamically imported so the Codex CLI is only spawned when this backend is
+    // actually selected. Uses the Codex CLI's stored login (no API key) unless
+    // CLAW_MEMORY_CODEX_API_KEY is set. Locked down for a pure text turn:
+    // read-only sandbox, no approvals, no network, no web search.
+    const { Codex } = await import("@openai/codex-sdk");
+    const apiKey = process.env.CLAW_MEMORY_CODEX_API_KEY;
+    const codex = new Codex(apiKey ? { apiKey } : {});
+    const thread = codex.startThread({
+        model: process.env.CLAW_MEMORY_CODEX_MODEL ?? model,
+        sandboxMode: "read-only",
+        skipGitRepoCheck: true,
+        approvalPolicy: "never",
+        networkAccessEnabled: false,
+        webSearchEnabled: false,
+        workingDirectory: os.tmpdir(),
+    });
+    const result = await thread.run(prompt);
+    return result.finalResponse ?? "";
+}
+async function completeAnthropic(prompt, model, maxTokens = 1024) {
+    const key = process.env.ANTHROPIC_API_KEY;
+    if (!key) {
+        throw new Error("CLAW_MEMORY_LLM_BACKEND=anthropic requires ANTHROPIC_API_KEY");
+    }
+    const base = process.env.ANTHROPIC_BASE_URL ?? "https://api.anthropic.com";
+    const res = await fetch(`${base.replace(/\/$/, "")}/v1/messages`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "x-api-key": key,
+            "anthropic-version": "2023-06-01",
+        },
+        body: JSON.stringify({
+            model,
+            max_tokens: maxTokens,
+            messages: [{ role: "user", content: prompt }],
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`anthropic API ${res.status}: ${await res.text()}`);
+    }
+    const json = (await res.json());
+    return (json.content ?? [])
+        .filter((b) => b.type === "text" && b.text)
+        .map((b) => b.text)
+        .join("");
+}
+async function completeOpenAi(prompt, model, maxTokens = 1024) {
+    const key = process.env.CLAW_MEMORY_OPENAI_API_KEY ?? process.env.OPENAI_API_KEY;
+    if (!key) {
+        throw new Error("CLAW_MEMORY_LLM_BACKEND=openai-compatible requires CLAW_MEMORY_OPENAI_API_KEY (or OPENAI_API_KEY)");
+    }
+    if (!model) {
+        throw new Error("CLAW_MEMORY_LLM_BACKEND=openai-compatible requires a model (set CLAW_MEMORY_MODEL)");
+    }
+    const base = process.env.CLAW_MEMORY_OPENAI_BASE_URL ??
+        process.env.OPENAI_BASE_URL ??
+        "https://api.openai.com/v1";
+    const res = await fetch(`${base.replace(/\/$/, "")}/chat/completions`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${key}`,
+        },
+        body: JSON.stringify({
+            model,
+            max_tokens: maxTokens,
+            messages: [{ role: "user", content: prompt }],
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`openai-compatible API ${res.status}: ${await res.text()}`);
+    }
+    const json = (await res.json());
+    return json.choices?.[0]?.message?.content ?? "";
+}

package/dist/core/logger.js

@@ -0,0 +1,19 @@
+// src/core/logger.ts
+//
+// Best-effort structured daily log at ~/.claw-memory/logs/claw-YYYY-MM-DD.log.
+// Never throws — logging must not break a memory operation or a hook.
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { dataDir } from "./paths.js";
+const logsDir = path.join(dataDir, "logs");
+export function log(event, data) {
+    try {
+        mkdirSync(logsDir, { recursive: true });
+        const now = new Date().toISOString();
+        const line = JSON.stringify({ t: now, event, ...(data ?? {}) }) + "\n";
+        appendFileSync(path.join(logsDir, `claw-${now.slice(0, 10)}.log`), line);
+    }
+    catch {
+        // logging is non-critical
+    }
+}

package/dist/core/logsearch/paths.js

@@ -0,0 +1,11 @@
+// src/core/logsearch/paths.ts
+//
+// Roots for raw agent transcript logs searched by the cc-search port.
+// Read-only; these belong to Claude Code / Codex, not to claw-memory.
+import os from "node:os";
+import path from "node:path";
+export const claudeProjectsRoot = path.join(os.homedir(), ".claude", "projects");
+export const codexSessionsRoot = path.join(os.homedir(), ".codex", "sessions");
+/** Max transcript size to scan; larger files are skipped (cc-search parity). */
+export const MAX_LOG_FILE_SIZE = 10 * 1024 * 1024;
+export const UUID_JSONL_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$/i;

package/dist/core/logsearch/recent.js

@@ -0,0 +1,40 @@
+// src/core/logsearch/recent.ts
+//
+// Enumerate Codex rollout transcripts newest-first, for batch distillation
+// (claw-memory distill-codex). Read-only over ~/.codex/sessions.
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { codexSessionsRoot } from "./paths.js";
+/** All Codex `*.jsonl` rollout files under ~/.codex/sessions, newest first. */
+export async function listCodexSessionFiles() {
+    const out = [];
+    const stack = [codexSessionsRoot];
+    while (stack.length) {
+        const cur = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(cur, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = join(cur, e.name);
+            if (e.isDirectory()) {
+                stack.push(full);
+            }
+            else if (e.isFile() && e.name.endsWith(".jsonl")) {
+                const s = await stat(full).catch(() => null);
+                if (s)
+                    out.push({ path: full, mtimeMs: s.mtimeMs });
+            }
+        }
+    }
+    out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return out;
+}
+/** Extract the session UUID from a rollout filename, else the path. */
+export function codexSessionId(filePath) {
+    const m = filePath.match(/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i);
+    return m ? m[1] : filePath;
+}