local-agentic-ai-mem 0.1.0

package/dist/mcp/server.js

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serve = serve;
+/**
+ * MCP server, speaking stdio and reading the local SQLite file directly.
+ *
+ * The hosted version shipped a shim that forwarded every call to an API. This
+ * is the server: no network hop, no API key, no account. That removes the
+ * whole class of credential problems along with roughly 200ms of round trip.
+ *
+ * Design note on the tool surface. Tools are *pull* — the model has to choose
+ * to call one, which is precisely how memory gets ignored. So the primary
+ * path is the hooks, which *push* context in unconditionally, and the tools
+ * here are deliberately few:
+ *
+ *   recall_memory  an escape hatch for an explicit "what did we decide about
+ *                  X?" that the automatic injection did not cover
+ *   save_memory    a deliberate act, which genuinely wants to be a tool
+ *
+ * `get_preferences` is gone. Project facts arrive at SessionStart whether or
+ * not anything asks for them, and every redundant tool is another chance to
+ * spend a turn fetching something the model already has. The same facts are
+ * also exposed as an MCP *resource*, which a client can attach without the
+ * model deciding anything.
+ */
+const path_1 = require("path");
+const fs_1 = require("fs");
+const child_process_1 = require("child_process");
+const db_1 = require("../db");
+const embed_1 = require("../lib/embed");
+const recall_1 = require("../lib/recall");
+const redact_1 = require("../lib/redact");
+const compose_1 = require("../lib/compose");
+const SUPPORTED_PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const TOOLS = [
+    {
+        name: "recall_memory",
+        description: "Look up past work: decisions, what was tried and abandoned, and context that is not in the code. Relevant memory is injected automatically at session start and on each prompt, so use this only when you need something specific that was not already provided.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Topic, error message, file, or decision to look for" },
+                limit: { type: "number", description: "Results to return (default 5, max 20)" },
+                scope: {
+                    type: "string",
+                    enum: ["auto", "project", "all"],
+                    description: "auto (default) ranks this project higher but still returns matches elsewhere.",
+                },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "save_memory",
+        description: "Record something that should still be true next session — a decision and its reasoning, an approach that failed and why, or context a human gave you that is not in the code.",
+        inputSchema: {
+            type: "object",
+            properties: { note: { type: "string", description: "What to remember" } },
+            required: ["note"],
+        },
+    },
+];
+function projectSlug() {
+    return process.env.AGENTIC_MEMORY_PROJECT || (0, path_1.basename)(process.cwd());
+}
+/**
+ * A memory is only trustworthy if the model can tell fresh from stale. Without
+ * this signal it has to distrust everything equally, which is the same as
+ * ignoring it.
+ */
+function freshness(files, anchorSha) {
+    if (!anchorSha || files.length === 0)
+        return null;
+    if (!(0, fs_1.existsSync)(".git"))
+        return null;
+    try {
+        for (const f of files.slice(0, 4)) {
+            if (!(0, fs_1.existsSync)(f))
+                continue;
+            const current = (0, child_process_1.execFileSync)("git", ["log", "-1", "--format=%H", "--", f], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: 1500,
+            }).trim();
+            if (current && current !== anchorSha)
+                return "file changed since — verify before relying on this";
+        }
+        return "still current";
+    }
+    catch {
+        return null;
+    }
+}
+function respond(id, result) {
+    process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
+}
+function respondError(id, message, code = -32603) {
+    process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
+}
+function textResult(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+}
+async function callTool(name, args) {
+    const slug = projectSlug();
+    const projectId = (0, db_1.upsertProject)(slug, process.cwd());
+    if (name === "recall_memory") {
+        const query = String(args?.query ?? "").trim();
+        if (!query)
+            throw new Error("query is required");
+        const limit = Math.min(Math.max(Number(args?.limit) || 5, 1), 20);
+        const scope = args?.scope === "project" || args?.scope === "all" ? args.scope : "auto";
+        const vec = await (0, embed_1.embed)(query);
+        const results = (0, recall_1.recall)({
+            queryText: query,
+            queryVec: vec,
+            projectId: scope === "all" ? undefined : projectId,
+            limit,
+        });
+        const scoped = scope === "project" ? results.filter((r) => r.projectId === projectId) : results;
+        return textResult(scoped.map((r) => ({
+            date: r.date.slice(0, 10),
+            project: r.project,
+            memory: r.text,
+            decisions: r.decisions.slice(0, 6),
+            files: r.files.slice(0, 10),
+            confidence: r.confidence,
+            ...(freshness(r.files, r.anchorSha) ? { freshness: freshness(r.files, r.anchorSha) } : {}),
+        })));
+    }
+    if (name === "save_memory") {
+        const raw = String(args?.note ?? "").trim();
+        if (!raw)
+            throw new Error("note is required");
+        if (raw.length > 10_000)
+            throw new Error("note too long (max 10 000 chars)");
+        const note = (0, redact_1.redact)(raw);
+        const [vec, promptVec] = await Promise.all([(0, embed_1.embed)((0, compose_1.indexText)(null, note)), (0, embed_1.embed)(note)]);
+        (0, db_1.insertMemory)({
+            projectId,
+            prompt: note,
+            content: note,
+            decisions: [],
+            files: [],
+            toolCalls: [],
+            gitCommit: null,
+            anchorSha: null,
+            confidence: "stated",
+            // A deliberate note is tier 2 by definition: a human decided it mattered.
+            tier: 2,
+            startedAt: new Date().toISOString(),
+            sessionId: null,
+            vec,
+            promptVec,
+        });
+        return { content: [{ type: "text", text: "Saved." }] };
+    }
+    throw new Error(`Unknown tool: ${name}`);
+}
+function serve() {
+    (0, db_1.db)(process.cwd());
+    process.stdin.setEncoding("utf8");
+    let buffer = "";
+    process.stdin.on("data", async (chunk) => {
+        buffer += chunk;
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            // JSON-RPC notifications carry no id and must never be answered.
+            const isNotification = msg.id === undefined || msg.id === null;
+            try {
+                if (msg.method === "initialize") {
+                    const asked = msg.params?.protocolVersion;
+                    respond(msg.id, {
+                        protocolVersion: SUPPORTED_PROTOCOLS.includes(asked) ? asked : SUPPORTED_PROTOCOLS[0],
+                        capabilities: { tools: {}, resources: {} },
+                        serverInfo: { name: "agentic-memory", version: "0.1.0" },
+                    });
+                }
+                else if (msg.method === "ping") {
+                    respond(msg.id, {});
+                }
+                else if (msg.method === "tools/list") {
+                    respond(msg.id, { tools: TOOLS });
+                }
+                else if (msg.method === "resources/list") {
+                    // Facts as a resource, so a client can attach them without the model
+                    // choosing to call anything.
+                    respond(msg.id, {
+                        resources: [
+                            {
+                                uri: `agentic-memory://project/${projectSlug()}/facts`,
+                                name: `What is true about ${projectSlug()}`,
+                                description: "Established conventions, hot files and constraints for this project.",
+                                mimeType: "text/markdown",
+                            },
+                        ],
+                    });
+                }
+                else if (msg.method === "resources/read") {
+                    const projectId = (0, db_1.upsertProject)(projectSlug(), process.cwd());
+                    const facts = (0, db_1.getFacts)(projectId);
+                    const body = facts.length
+                        ? facts.map((f) => `- [${f.kind}] ${f.fact}`).join("\n")
+                        : "_No established facts for this project yet._";
+                    respond(msg.id, {
+                        contents: [
+                            {
+                                uri: String(msg.params?.uri ?? ""),
+                                mimeType: "text/markdown",
+                                text: `# What is true about ${projectSlug()}\n\n${body}\n`,
+                            },
+                        ],
+                    });
+                }
+                else if (msg.method === "tools/call") {
+                    const res = await callTool(msg.params?.name, msg.params?.arguments ?? {});
+                    respond(msg.id, res);
+                }
+                else if (!isNotification) {
+                    respondError(msg.id, `Method not found: ${msg.method}`, -32601);
+                }
+            }
+            catch (e) {
+                if (!isNotification)
+                    respondError(msg.id, e?.message ?? String(e));
+            }
+        }
+    });
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "local-agentic-ai-mem",
+  "version": "0.1.0",
+  "description": "Local-first memory for Claude Code. Your code and your memory never leave your machine.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "agentic-memory": "dist/index.js",
+    "local-agentic-ai-mem": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "memory",
+    "local-first",
+    "sqlite"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "fastembed": "^1.14.4"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.4"
+  }
+}

package/templates/hooks/post-tool-use.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// agentic-memory — PostToolUse. Records what the turn actually did.
+import { readFileSync, writeFileSync, existsSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+
+async function main() {
+  let raw = ''
+  process.stdin.setEncoding('utf8')
+  for await (const c of process.stdin) raw += c
+  let p = {}
+  try { p = JSON.parse(raw) } catch { return }
+  if (!p.session_id || !p.tool_name) return
+
+  const file = join(homedir(), '.agentic-memory', 'turns', p.session_id + '.json')
+  if (!existsSync(file)) return
+  try {
+    const turn = JSON.parse(readFileSync(file, 'utf8'))
+    const input = p.tool_input || {}
+    const target = input.file_path || input.path || input.command || input.pattern || ''
+    turn.tool_calls.push({ tool: p.tool_name, target: String(target).slice(0, 300) })
+    if (['Write', 'Edit', 'MultiEdit', 'NotebookEdit'].includes(p.tool_name) && input.file_path) {
+      if (!turn.files.includes(input.file_path)) turn.files.push(input.file_path)
+    }
+    if (turn.tool_calls.length > 400) turn.tool_calls = turn.tool_calls.slice(-400)
+    writeFileSync(file, JSON.stringify(turn))
+  } catch {}
+}
+main().catch(() => {})

package/templates/hooks/session-start.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// agentic-memory — SessionStart.
+//
+// Injects tier 1: the small set of things known to be true about this project.
+// Always, whether or not anything asks. Tools are pull and get ignored; hooks
+// are push. Measured at 14.5% coverage on held-out future work for under a
+// kilobyte — more than searching the entire corpus achieved on its own.
+import { createRequire } from 'module'
+const require = createRequire(import.meta.url)
+// Stamped at install time — these hooks run outside any node_modules tree.
+const ROOT = '__AGENTIC_MEMORY_ROOT__'
+
+async function main() {
+  let raw = ''
+  process.stdin.setEncoding('utf8')
+  for await (const c of process.stdin) raw += c
+  let payload = {}
+  try { payload = JSON.parse(raw) } catch {}
+  if (payload.source === 'clear' || payload.source === 'compact') return
+
+  const { db, upsertProject, getFacts, recordInjection } = require(ROOT + '/dist/db')
+  const { distinctiveTokens } = require(ROOT + '/dist/lib/compliance')
+  const { maintain } = require(ROOT + '/dist/lib/maintain')
+  const { basename } = require('path')
+
+  const cwd = payload.cwd || process.cwd()
+  db(cwd)
+  const slug = process.env.AGENTIC_MEMORY_PROJECT || basename(cwd)
+  const projectId = upsertProject(slug, cwd)
+
+  // Opportunistic maintenance — there is no cron on a laptop.
+  try { maintain() } catch {}
+
+  const facts = getFacts(projectId)
+  if (facts.length === 0) return
+
+  const lines = [`# What is true about ${slug}`, '']
+  for (const f of facts) {
+    lines.push(`- [${f.kind}] ${f.fact}${f.confidence === 'pushed' ? ' ✓' : ''}`)
+  }
+  lines.push('')
+  lines.push('These were derived from your own past sessions. Treat them as current')
+  lines.push('unless the code in front of you says otherwise.')
+
+  const text = lines.join('\n')
+
+  // Record what went in, so the Stop hook can ask what the session did with
+  // it. Without this the only thing ever measured is retrieval.
+  try {
+    const files = []
+    const pitfallFiles = []
+    for (const f of facts) {
+      let fs = []
+      try { fs = JSON.parse(f.files || '[]') } catch {}
+      for (const x of fs) {
+        if (!files.includes(x)) files.push(x)
+        if (f.kind === 'pitfall' && !pitfallFiles.includes(x)) pitfallFiles.push(x)
+      }
+    }
+    recordInjection({
+      sessionId: payload.session_id || 'unknown',
+      projectId, kind: 'facts', memoryIds: [],
+      files, tokens: distinctiveTokens(text, ''), pitfallFiles,
+    })
+  } catch {}
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: text },
+  }))
+  process.stderr.write(`\x1b[36m🧠 ${facts.length} project facts loaded for "${slug}"\x1b[0m\n`)
+}
+main().catch(() => {})

package/templates/hooks/stop.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// agentic-memory — Stop. Finalise the turn and store it, or discard it.
+//
+// The gate is what the turn produced, not how long the prompt was. A turn that
+// changed nothing and concluded nothing is not a memory.
+import { createRequire } from 'module'
+import { readFileSync, existsSync, unlinkSync } from 'fs'
+import { execFileSync } from 'child_process'
+import { homedir } from 'os'
+import { join, basename } from 'path'
+const require = createRequire(import.meta.url)
+// Stamped at install time — these hooks run outside any node_modules tree.
+const ROOT = '__AGENTIC_MEMORY_ROOT__'
+
+function git(args, cwd) {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }).trim()
+  } catch { return '' }
+}
+
+async function main() {
+  let raw = ''
+  process.stdin.setEncoding('utf8')
+  for await (const c of process.stdin) raw += c
+  let p = {}
+  try { p = JSON.parse(raw) } catch { return }
+  if (!p.session_id || p.reason === 'clear' || p.reason === 'resume') return
+
+  const file = join(homedir(), '.agentic-memory', 'turns', p.session_id + '.json')
+  if (!existsSync(file)) return
+  let turn
+  try { turn = JSON.parse(readFileSync(file, 'utf8')) } catch { return }
+  unlinkSync(file)
+
+  const { db, upsertProject, insertMemory } = require(ROOT + '/dist/db')
+  const { embed } = require(ROOT + '/dist/lib/embed')
+  const { extractMemory } = require(ROOT + '/dist/lib/extract')
+  const { composeAtomContent, indexText } = require(ROOT + '/dist/lib/compose')
+  const { assignTier, gradeConfidence } = require(ROOT + '/dist/lib/tiers')
+  const { redact } = require(ROOT + '/dist/lib/redact')
+  const { openInjections, resolveInjection } = require(ROOT + '/dist/db')
+  const { readTranscript, scoreInjection } = require(ROOT + '/dist/lib/compliance')
+
+  const cwd = turn.cwd || p.cwd || process.cwd()
+
+  // Prefer the transcript — it holds Claude's own statements about what
+  // happened, which is where the durable knowledge is.
+  let extracted = null
+  let transcript = null
+  if (p.transcript_path && existsSync(p.transcript_path)) {
+    try {
+      transcript = readFileSync(p.transcript_path, 'utf8')
+      extracted = extractMemory(transcript)
+    } catch {}
+  }
+
+  // Close out whatever was injected this session. Done before the save-or-skip
+  // decision below, because a session that produced no memory still tells us
+  // whether the memory it was given got used.
+  if (transcript) {
+    try {
+      db(cwd)
+      const facts = readTranscript(transcript)
+      for (const inj of openInjections(p.session_id)) {
+        resolveInjection(inj.id, scoreInjection({
+          files: JSON.parse(inj.files || '[]'),
+          tokens: JSON.parse(inj.tokens || '[]'),
+          pitfallFiles: JSON.parse(inj.pitfall_files || '[]'),
+        }, facts))
+      }
+    } catch {}
+  }
+
+  const decisions = extracted?.decisions ?? []
+  const files = [...new Set([...(turn.files || []), ...(extracted?.files_touched ?? [])])]
+  const composed = extracted?.content
+    ? { content: extracted.content, decisions }
+    : composeAtomContent({ prompt: turn.prompt, decisions, files_touched: files, tool_calls: turn.tool_calls, git_commit: null })
+
+  if (!composed) {
+    process.stderr.write('\x1b[90m· nothing durable to remember\x1b[0m\n')
+    return
+  }
+
+  const head = git(['rev-parse', 'HEAD'], cwd)
+  const upstream = git(['rev-parse', '--abbrev-ref', '@{u}'], cwd)
+  const pushed = upstream ? git(['branch', '-r', '--contains', head], cwd) !== '' : false
+
+  const content = redact(composed.content)
+  const prompt = redact(turn.prompt)
+  const safeDecisions = (composed.decisions || []).map(redact)
+
+  const [vec, promptVec] = await Promise.all([embed(indexText(prompt, content)), embed(prompt)])
+
+  db(cwd)
+  const slug = process.env.AGENTIC_MEMORY_PROJECT || basename(cwd)
+  const projectId = upsertProject(slug, cwd)
+
+  const atom = { prompt, decisions: safeDecisions, files_touched: files, tool_calls: turn.tool_calls, git_commit: head || null }
+  insertMemory({
+    projectId, prompt, content,
+    decisions: safeDecisions, files, toolCalls: turn.tool_calls,
+    gitCommit: head || null, anchorSha: head || null,
+    confidence: gradeConfidence({ git_commit: head || null, git_pushed: pushed }),
+    tier: assignTier(atom),
+    startedAt: turn.started_at || new Date().toISOString(),
+    sessionId: p.session_id,
+    vec, promptVec,
+  })
+
+  process.stderr.write(`\x1b[36m🧠 remembered — ${content.slice(0, 64)}\x1b[0m\n`)
+}
+main().catch(() => {})

package/templates/hooks/user-prompt-submit.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// agentic-memory — UserPromptSubmit.
+//
+// Records the turn and injects relevant past work. This is the push path that
+// replaces asking the model to call a search tool.
+import { createRequire } from 'module'
+import { writeFileSync, mkdirSync } from 'fs'
+import { homedir } from 'os'
+import { join, basename } from 'path'
+const require = createRequire(import.meta.url)
+// Stamped at install time — these hooks run outside any node_modules tree.
+const ROOT = '__AGENTIC_MEMORY_ROOT__'
+
+const FILLER = /^(thanks|thank you|ok|okay|yes|go)\.?\??$/i
+const THRESHOLD = parseFloat(process.env.AGENTIC_MEMORY_THRESHOLD || '') || 0.35
+
+async function main() {
+  let raw = ''
+  process.stdin.setEncoding('utf8')
+  for await (const c of process.stdin) raw += c
+  let payload = {}
+  try { payload = JSON.parse(raw) } catch { return }
+  const { session_id, prompt, cwd } = payload
+  if (!session_id || !prompt) return
+
+  // Open the turn so the Stop hook can finalise it.
+  const dir = join(homedir(), '.agentic-memory', 'turns')
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, session_id + '.json'), JSON.stringify({
+    prompt, cwd: cwd || process.cwd(), started_at: new Date().toISOString(), tool_calls: [], files: [],
+  }))
+
+  if (prompt.trim().length < 12 || FILLER.test(prompt.trim())) return
+
+  try {
+    const { db, upsertProject, recordInjection } = require(ROOT + '/dist/db')
+    const { distinctiveTokens } = require(ROOT + '/dist/lib/compliance')
+    const { embed } = require(ROOT + '/dist/lib/embed')
+    const { recall } = require(ROOT + '/dist/lib/recall')
+
+    db(cwd || process.cwd())
+    const projectId = upsertProject(process.env.AGENTIC_MEMORY_PROJECT || basename(cwd || process.cwd()), cwd)
+    const vec = await embed(prompt)
+    const hits = recall({ queryText: prompt, queryVec: vec, projectId, limit: 3 })
+    if (hits.length === 0 || hits[0].score < THRESHOLD * hits[0].score) return
+
+    const lines = ['<memory>', 'Relevant past work — use it, do not narrate it.', '']
+    for (const h of hits) {
+      lines.push(`• ${h.text}`)
+      if (h.files.length) lines.push(`  files: ${h.files.slice(0, 4).join(', ')}`)
+    }
+    lines.push('')
+    lines.push('If the code in front of you disagrees, the code wins.')
+    lines.push('</memory>')
+
+    const text = lines.join('\n')
+    try {
+      const files = []
+      for (const h of hits) for (const f of (h.files || [])) if (!files.includes(f)) files.push(f)
+      recordInjection({
+        sessionId: session_id, projectId, kind: 'recall',
+        memoryIds: hits.map((h) => h.id), files,
+        tokens: distinctiveTokens(text, prompt), pitfallFiles: [],
+      })
+    } catch {}
+
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text },
+    }))
+  } catch {}
+}
+main().catch(() => {})