@tznthou/ccrecall 0.1.2

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":""}

package/dist/mcp/server.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+import path from 'node:path';
+import os from 'node:os';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Database } from '../core/database.js';
+import { registerTools } from './tools.js';
+const DB_PATH = process.env.CCRECALL_DB_PATH ?? path.join(os.homedir(), '.ccrecall', 'ccrecall.db');
+async function main() {
+    const db = new Database(DB_PATH);
+    const server = new McpServer({ name: 'ccrecall', version: '0.2.0' }, {
+        instructions: 'ccRecall is a local memory service for Claude Code. ' +
+            'Use recall_query to search past decisions, discoveries, and patterns ' +
+            'when the user references prior work or you need context from earlier sessions.',
+    });
+    registerTools(server, db);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`ccRecall MCP server running on stdio (db: ${DB_PATH})`);
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.on(signal, () => {
+            db.close();
+            process.exit(0);
+        });
+    }
+}
+main().catch((err) => {
+    console.error('MCP server fatal:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":";AACA,sCAAsC;AACtC,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,WAAW,EAAE,aAAa,CAAC,CAAA;AAEnG,KAAK,UAAU,IAAI;IACjB,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,OAAO,CAAC,CAAA;IAChC,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,EACtC;QACE,YAAY,EACV,sDAAsD;YACtD,uEAAuE;YACvE,gFAAgF;KACnF,CACF,CAAA;IAED,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAEzB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAA;IAC5C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAC/B,OAAO,CAAC,KAAK,CAAC,6CAA6C,OAAO,GAAG,CAAC,CAAA;IAEtE,KAAK,MAAM,MAAM,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAU,EAAE,CAAC;QACpD,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACtB,EAAE,CAAC,KAAK,EAAE,CAAA;YACV,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC,CAAC,CAAA;IACJ,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAA;IACvC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,39 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Database } from '../core/database.js';
+import { MemoryService } from '../core/memory-service.js';
+import type { Memory, MemoryType, KnowledgeDepth } from '../core/types.js';
+type McpTextResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: true;
+};
+export declare function formatMemories(memories: Memory[], query: string): string;
+export declare function recallQueryHandler(db: Database, memoryService: MemoryService, args: {
+    query: string;
+    limit?: number;
+}): McpTextResult;
+interface TopicCluster {
+    topic: string;
+    depth: KnowledgeDepth;
+    mentionCount: number;
+    memories: Memory[];
+}
+export declare function formatContextResult(clusters: TopicCluster[], unmatchedKeywords: string[], fallbackMemories: Memory[] | null, keywords: string[]): string;
+export declare function recallContextHandler(db: Database, memoryService: MemoryService, args: {
+    projectId: string;
+    keywords: string[];
+    memoryLimit?: number;
+}): McpTextResult;
+export declare function recallSaveHandler(db: Database, args: {
+    content: string;
+    type: MemoryType;
+    sessionId?: string | null;
+    messageId?: string | null;
+    confidence?: number;
+    projectId?: string | null;
+}): McpTextResult;
+export declare function registerTools(server: McpServer, db: Database): void;
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/dist/mcp/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAM1E,KAAK,aAAa,GAAG;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC9C,OAAO,CAAC,EAAE,IAAI,CAAA;CACf,CAAA;AAqBD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,QAAQ,EACZ,aAAa,EAAE,aAAa,EAC5B,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACtC,aAAa,CAUf;AAaD,UAAU,YAAY;IACpB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,cAAc,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,EAAE,EACxB,iBAAiB,EAAE,MAAM,EAAE,EAC3B,gBAAgB,EAAE,MAAM,EAAE,GAAG,IAAI,EACjC,QAAQ,EAAE,MAAM,EAAE,GACjB,MAAM,CAuBR;AAQD,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,QAAQ,EACZ,aAAa,EAAE,aAAa,EAC5B,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE,aAAa,CAwDf;AAED,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE;IACJ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,UAAU,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B,GACA,aAAa,CAcf;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,GAAG,IAAI,CA8EnE"}

package/dist/mcp/tools.js

@@ -0,0 +1,215 @@
+// SPDX-License-Identifier: Apache-2.0
+import * as z from 'zod';
+import { MemoryService } from '../core/memory-service.js';
+import { deriveDepth } from '../core/types.js';
+import { normalizeTopicKey } from '../core/topic-extractor.js';
+const MEMORY_TYPES = ['decision', 'discovery', 'preference', 'pattern', 'feedback'];
+function textResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function textError(prefix, err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: 'text', text: `${prefix}: ${msg}` }], isError: true };
+}
+const recallQueryInput = {
+    query: z.string().min(1).describe('FTS5 search query (keywords or phrase)'),
+    limit: z.number().int().positive().max(50).optional().describe('Max results (default 10, max 50)'),
+};
+function formatMemoryLine(m) {
+    const conf = m.confidence !== 1 ? ` (conf ${m.confidence.toFixed(2)})` : '';
+    return `- [${m.type}]${conf} ${m.content}`;
+}
+export function formatMemories(memories, query) {
+    if (memories.length === 0)
+        return `No memories found for: ${query}`;
+    return memories.map(formatMemoryLine).join('\n');
+}
+export function recallQueryHandler(db, memoryService, args) {
+    try {
+        const memories = db.queryMemories(args.query, args.limit ?? 10);
+        // Phase 4c: touch returned memories so access_count reflects real usage,
+        // extending their half-life under the decay formula. touch noops on [].
+        memoryService.touch(memories.map(m => m.id));
+        return textResult(formatMemories(memories, args.query));
+    }
+    catch (err) {
+        return textError('Error querying memories', err);
+    }
+}
+const recallSaveInput = {
+    content: z.string().min(1).describe('Memory content — the fact or insight to remember'),
+    type: z.enum(MEMORY_TYPES).describe('Memory category'),
+    sessionId: z.string().nullable().optional().describe('Origin session ID (optional)'),
+    messageId: z.string().nullable().optional().describe('Origin message ID (optional)'),
+    confidence: z.number().min(0).max(1).optional().describe('Confidence 0-1 (default 1)'),
+    projectId: z.string().nullable().optional().describe('Project ID for scoped queries. Session-backed memories derive this from sessions.project_id automatically; manual memories should set this to avoid cross-project leakage.'),
+};
+export function formatContextResult(clusters, unmatchedKeywords, fallbackMemories, keywords) {
+    if (clusters.length === 0 && (!fallbackMemories || fallbackMemories.length === 0)) {
+        return `No relevant memories for: ${keywords.join(', ')}`;
+    }
+    const parts = [`# Relevant memories for: ${keywords.join(', ')}`, ''];
+    for (const c of clusters) {
+        parts.push(`## Topic: ${c.topic} (${c.depth}, ${c.mentionCount} mentions)`);
+        if (c.memories.length === 0) {
+            parts.push('(no memories linked yet)');
+        }
+        else {
+            for (const m of c.memories)
+                parts.push(formatMemoryLine(m));
+        }
+        parts.push('');
+    }
+    if (fallbackMemories && fallbackMemories.length > 0) {
+        parts.push('## FTS fallback (no topic match)');
+        for (const m of fallbackMemories)
+            parts.push(formatMemoryLine(m));
+        parts.push('');
+    }
+    if (unmatchedKeywords.length > 0) {
+        parts.push(`(No topic match for: ${unmatchedKeywords.join(', ')})`);
+    }
+    return parts.join('\n').trimEnd();
+}
+const recallContextInput = {
+    projectId: z.string().min(1).describe('Project ID (derived from cwd, e.g. "-Users-foo-my-project")'),
+    keywords: z.array(z.string().min(1)).min(1).describe('Candidate topic keywords (e.g. ["typescript", "mcp"])'),
+    memoryLimit: z.number().int().positive().max(20).optional().describe('Max memories per topic (default 5)'),
+};
+export function recallContextHandler(db, memoryService, args) {
+    try {
+        const memoryLimit = args.memoryLimit ?? 5;
+        const normalized = args.keywords
+            .map(k => ({ raw: k, key: normalizeTopicKey(k) }))
+            .filter((x) => x.key !== null);
+        const clusters = [];
+        const unmatched = [];
+        for (const { raw, key } of normalized) {
+            const topic = db.getTopic(key, args.projectId);
+            if (!topic) {
+                unmatched.push(raw);
+                continue;
+            }
+            const memories = db.getMemoriesByTopics(args.projectId, [key], memoryLimit);
+            clusters.push({
+                topic: key,
+                depth: deriveDepth(topic.mentionCount),
+                mentionCount: topic.mentionCount,
+                memories,
+            });
+        }
+        // FTS fallback if no topic matched — per-keyword union (queryMemories quotes every
+        // token into a phrase, so "foo OR bar" collapses to a phrase query, not a boolean OR)
+        let fallback = null;
+        if (clusters.length === 0 && args.keywords.length > 0) {
+            const seen = new Set();
+            const aggregated = [];
+            for (const kw of args.keywords) {
+                if (aggregated.length >= memoryLimit)
+                    break;
+                const results = db.queryMemories(kw, memoryLimit, args.projectId);
+                for (const m of results) {
+                    if (aggregated.length >= memoryLimit)
+                        break;
+                    if (!seen.has(m.id)) {
+                        seen.add(m.id);
+                        aggregated.push(m);
+                    }
+                }
+            }
+            fallback = aggregated;
+        }
+        // Phase 4c: gather all memory ids surfaced (clusters + fallback) and touch once.
+        // MemoryService.touch dedupes internally, so a memory appearing in multiple
+        // clusters still only bumps access_count by 1 per request.
+        const clusterIds = clusters.flatMap(c => c.memories.map(m => m.id));
+        const fallbackIds = fallback?.map(m => m.id) ?? [];
+        memoryService.touch([...clusterIds, ...fallbackIds]);
+        return textResult(formatContextResult(clusters, unmatched, fallback, args.keywords));
+    }
+    catch (err) {
+        return textError('Error building context', err);
+    }
+}
+export function recallSaveHandler(db, args) {
+    try {
+        const id = db.saveMemory({
+            sessionId: args.sessionId ?? null,
+            messageId: args.messageId ?? null,
+            content: args.content,
+            type: args.type,
+            confidence: args.confidence ?? 1,
+            projectId: args.projectId ?? null,
+        });
+        return textResult(`Saved memory #${id} (type: ${args.type})`);
+    }
+    catch (err) {
+        return textError('Error saving memory', err);
+    }
+}
+export function registerTools(server, db) {
+    const memoryService = new MemoryService(db);
+    server.registerTool('recall_query', {
+        title: 'Query ccRecall Memories',
+        description: [
+            'Search ccRecall memories by keyword (FTS5 full-text search).',
+            '',
+            'USE THIS WHEN:',
+            '- User references past work ("what did we decide", "previously", "last time")',
+            '- Continuing a topic from a prior Claude Code session',
+            '- You need context about past decisions, discoveries, patterns, or preferences',
+            '',
+            'Returns: formatted list of matching memories with type and confidence.',
+        ].join('\n'),
+        inputSchema: recallQueryInput,
+        // Phase 4c touch mutates access_count / last_accessed, so this tool is no
+        // longer read-only or idempotent. Mislabelling would let MCP hosts retry
+        // or cache under the wrong assumption and silently skew recall ranking.
+        annotations: { readOnlyHint: false, idempotentHint: false },
+    }, async (args) => recallQueryHandler(db, memoryService, args));
+    server.registerTool('recall_context', {
+        title: 'Get Topic-Clustered Memories',
+        description: [
+            'Retrieve memories clustered by topic (uses knowledge_map, not plain FTS).',
+            '',
+            'USE THIS WHEN:',
+            '- Starting work on a topic and want to see what you already know about it',
+            '- User asks "what do we know about X" / "what\'s our take on Y"',
+            '- You want memories grouped by theme, with knowledge depth signals',
+            '',
+            'vs recall_query:',
+            '- recall_query: raw FTS search, returns flat list',
+            '- recall_context: topic-aware, groups results, shows mention count + depth',
+            '',
+            'Returns: markdown with memory clusters by topic, plus FTS fallback if no topic match.',
+        ].join('\n'),
+        inputSchema: recallContextInput,
+        // Phase 4c touch mutates access_count / last_accessed per surfaced memory
+        // (with cross-cluster dedup), so this tool is no longer read-only or
+        // idempotent — same reasoning as recall_query above.
+        annotations: { readOnlyHint: false, idempotentHint: false },
+    }, async (args) => recallContextHandler(db, memoryService, args));
+    server.registerTool('recall_save', {
+        title: 'Save Memory to ccRecall',
+        description: [
+            'Save a new memory to ccRecall for recall in future sessions.',
+            '',
+            'USE THIS WHEN:',
+            '- User states a decision worth remembering across sessions',
+            '- You discover something non-obvious (bug cause, API quirk, design constraint)',
+            '- User explicitly says "remember this" or "save this"',
+            '',
+            'Types:',
+            '- decision: explicit choice with rationale',
+            '- discovery: non-obvious finding',
+            '- preference: user style or convention',
+            '- pattern: recurring workflow or code template',
+            '- feedback: user correction on past work',
+            '',
+            'Returns: memory ID and type confirmation.',
+        ].join('\n'),
+        inputSchema: recallSaveInput,
+        annotations: { readOnlyHint: false, idempotentHint: false },
+    }, async (args) => recallSaveHandler(db, args));
+}
+//# sourceMappingURL=tools.js.map

package/dist/mcp/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AAGxB,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAEzD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAE9D,MAAM,YAAY,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,CAAU,CAAA;AAO5F,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;AACvD,CAAC;AAED,SAAS,SAAS,CAAC,MAAc,EAAE,GAAY;IAC7C,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC5D,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,GAAG,MAAM,KAAK,GAAG,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AAC3F,CAAC;AAED,MAAM,gBAAgB,GAAG;IACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,wCAAwC,CAAC;IAC3E,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;CACnG,CAAA;AAED,SAAS,gBAAgB,CAAC,CAAS;IACjC,MAAM,IAAI,GAAG,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IAC3E,OAAO,MAAM,CAAC,CAAC,IAAI,IAAI,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,CAAA;AAC5C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAkB,EAAE,KAAa;IAC9D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,0BAA0B,KAAK,EAAE,CAAA;IACnE,OAAO,QAAQ,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAClD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,EAAY,EACZ,aAA4B,EAC5B,IAAuC;IAEvC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAA;QAC/D,yEAAyE;QACzE,wEAAwE;QACxE,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QAC5C,OAAO,UAAU,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;IACzD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,SAAS,CAAC,yBAAyB,EAAE,GAAG,CAAC,CAAA;IAClD,CAAC;AACH,CAAC;AAED,MAAM,eAAe,GAAG;IACtB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,kDAAkD,CAAC;IACvF,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACtD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IACpF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IACpF,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACtF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAClD,4KAA4K,CAC7K;CACF,CAAA;AASD,MAAM,UAAU,mBAAmB,CACjC,QAAwB,EACxB,iBAA2B,EAC3B,gBAAiC,EACjC,QAAkB;IAElB,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,gBAAgB,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QAClF,OAAO,6BAA6B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;IAC3D,CAAC;IACD,MAAM,KAAK,GAAa,CAAC,4BAA4B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;IAC/E,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,YAAY,YAAY,CAAC,CAAA;QAC3E,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAA;QACxC,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ;gBAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAA;QAC7D,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChB,CAAC;IACD,IAAI,gBAAgB,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,KAAK,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAA;QAC9C,KAAK,MAAM,CAAC,IAAI,gBAAgB;YAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAA;QACjE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChB,CAAC;IACD,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,wBAAwB,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACrE,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAA;AACnC,CAAC;AAED,MAAM,kBAAkB,GAAG;IACzB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6DAA6D,CAAC;IACpG,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,uDAAuD,CAAC;IAC7G,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;CAC3G,CAAA;AAED,MAAM,UAAU,oBAAoB,CAClC,EAAY,EACZ,aAA4B,EAC5B,IAAqE;IAErE,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,CAAC,CAAA;QACzC,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ;aAC7B,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;aACjD,MAAM,CAAC,CAAC,CAAC,EAAqC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,CAAA;QAEnE,MAAM,QAAQ,GAAmB,EAAE,CAAA;QACnC,MAAM,SAAS,GAAa,EAAE,CAAA;QAE9B,KAAK,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,UAAU,EAAE,CAAC;YACtC,MAAM,KAAK,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;YAC9C,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;gBACnB,SAAQ;YACV,CAAC;YACD,MAAM,QAAQ,GAAG,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,CAAA;YAC3E,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,GAAG;gBACV,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,YAAY,CAAC;gBACtC,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,QAAQ;aACT,CAAC,CAAA;QACJ,CAAC;QAED,mFAAmF;QACnF,sFAAsF;QACtF,IAAI,QAAQ,GAAoB,IAAI,CAAA;QACpC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;YAC9B,MAAM,UAAU,GAAa,EAAE,CAAA;YAC/B,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAC/B,IAAI,UAAU,CAAC,MAAM,IAAI,WAAW;oBAAE,MAAK;gBAC3C,MAAM,OAAO,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;gBACjE,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;oBACxB,IAAI,UAAU,CAAC,MAAM,IAAI,WAAW;wBAAE,MAAK;oBAC3C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;wBACpB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;wBACd,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;oBACpB,CAAC;gBACH,CAAC;YACH,CAAC;YACD,QAAQ,GAAG,UAAU,CAAA;QACvB,CAAC;QAED,iFAAiF;QACjF,4EAA4E;QAC5E,2DAA2D;QAC3D,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QACnE,MAAM,WAAW,GAAG,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAA;QAClD,aAAa,CAAC,KAAK,CAAC,CAAC,GAAG,UAAU,EAAE,GAAG,WAAW,CAAC,CAAC,CAAA;QAEpD,OAAO,UAAU,CAAC,mBAAmB,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAA;IACtF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,SAAS,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAA;IACjD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,EAAY,EACZ,IAOC;IAED,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC;YACvB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;YACjC,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;YACjC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC;YAChC,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;SAClC,CAAC,CAAA;QACF,OAAO,UAAU,CAAC,iBAAiB,EAAE,WAAW,IAAI,CAAC,IAAI,GAAG,CAAC,CAAA;IAC/D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,SAAS,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAA;IAC9C,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAiB,EAAE,EAAY;IAC3D,MAAM,aAAa,GAAG,IAAI,aAAa,CAAC,EAAE,CAAC,CAAA;IAC3C,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,KAAK,EAAE,yBAAyB;QAChC,WAAW,EAAE;YACX,8DAA8D;YAC9D,EAAE;YACF,gBAAgB;YAChB,+EAA+E;YAC/E,uDAAuD;YACvD,gFAAgF;YAChF,EAAE;YACF,wEAAwE;SACzE,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,WAAW,EAAE,gBAAgB;QAC7B,0EAA0E;QAC1E,yEAAyE;QACzE,wEAAwE;QACxE,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE;KAC5D,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,CAAC,CAC5D,CAAA;IAED,MAAM,CAAC,YAAY,CACjB,gBAAgB,EAChB;QACE,KAAK,EAAE,8BAA8B;QACrC,WAAW,EAAE;YACX,2EAA2E;YAC3E,EAAE;YACF,gBAAgB;YAChB,2EAA2E;YAC3E,iEAAiE;YACjE,oEAAoE;YACpE,EAAE;YACF,kBAAkB;YAClB,mDAAmD;YACnD,4EAA4E;YAC5E,EAAE;YACF,uFAAuF;SACxF,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,WAAW,EAAE,kBAAkB;QAC/B,0EAA0E;QAC1E,qEAAqE;QACrE,qDAAqD;QACrD,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE;KAC5D,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,CAAC,CAC9D,CAAA;IAED,MAAM,CAAC,YAAY,CACjB,aAAa,EACb;QACE,KAAK,EAAE,yBAAyB;QAChC,WAAW,EAAE;YACX,8DAA8D;YAC9D,EAAE;YACF,gBAAgB;YAChB,4DAA4D;YAC5D,gFAAgF;YAChF,uDAAuD;YACvD,EAAE;YACF,QAAQ;YACR,4CAA4C;YAC5C,kCAAkC;YAClC,wCAAwC;YACxC,gDAAgD;YAChD,0CAA0C;YAC1C,EAAE;YACF,2CAA2C;SAC5C,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,WAAW,EAAE,eAAe;QAC5B,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE;KAC5D,EACD,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,EAAE,EAAE,IAAI,CAAC,CAC5C,CAAA;AACH,CAAC"}

package/hooks/README.md

@@ -0,0 +1,78 @@
+# ccRecall Claude Code Hooks
+
+Hook scripts that let Claude Code's lifecycle events trigger ccRecall actions.
+
+## Prerequisites
+
+The ccRecall HTTP service must be running on `127.0.0.1:7749` (or the port set via `CCRECALL_PORT`). Start it with:
+
+```bash
+pnpm dev       # from the ccRecall repo
+```
+
+If the service is not running, hooks log a warning to stderr and exit cleanly — they never block Claude Code.
+
+## Available Hooks
+
+| Script | Claude Code Event | Action |
+|--------|------------------|--------|
+| `session-start.mjs` | `SessionStart` | GET `/memory/query` with the project name, write matching memories to stdout (Claude prepends them to context) |
+| `session-end.mjs` | `SessionEnd` | POST `/session/end` to harvest the just-ended session into a memory |
+
+## Installation
+
+Add to `~/.claude/settings.json` (or your project's `.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /Users/tznthou/Documents/ccRecall/hooks/session-start.mjs"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /Users/tznthou/Documents/ccRecall/hooks/session-end.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Adjust the path to match your ccRecall clone location.
+
+## Environment Variables
+
+- `CCRECALL_PORT` — override the HTTP port (default `7749`)
+
+## Verifying the Hook
+
+Trigger manually:
+
+```bash
+echo '{"session_id":"test-session","hook_event_name":"SessionEnd","reason":"other"}' \
+  | node /Users/tznthou/Documents/ccRecall/hooks/session-end.mjs
+```
+
+With ccRecall running, this POSTs to `/session/end`. The response (success or 404) is logged to stderr only on failure.
+
+## Design Notes
+
+- **Non-blocking**: hooks exit quickly; errors go to stderr and the script exits 0 — never blocks Claude Code
+- **Skip on `resume`**:
+  - SessionEnd: `reason === 'resume'` means the session continues
+  - SessionStart: `source === 'resume'` means the context is already loaded
+- **SessionStart query strategy**: uses the last path segment of `cwd` as a keyword against FTS5 — simple, no-prompt-yet heuristic; Phase 3+ will add smarter selection
+- **SessionStart stdout = context injection**: only memories are written to stdout; all errors and diagnostics go to stderr to avoid polluting Claude's context
+- **Timeouts**: SessionEnd 5s, SessionStart 2s (tighter because it sits on the pre-prompt critical path)

package/hooks/session-end.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// ccRecall SessionEnd hook — harvests the just-ended session into memories.
+// Wired via ~/.claude/settings.json hooks.SessionEnd. Non-blocking.
+import http from 'node:http'
+
+const PORT = Number(process.env.CCRECALL_PORT ?? 7749)
+const HOST = '127.0.0.1'
+const TIMEOUT_MS = 5000
+
+async function readStdin() {
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+// Strip CR/LF and other control chars so attacker-controlled response bodies
+// can't forge log entries when interpolated into console.error.
+function sanitizeForLog(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s).replace(/[\r\n\x00-\x1f\x7f]/g, ' ')
+}
+
+function postSessionEnd(sessionId) {
+  return new Promise((resolve) => {
+    const payload = JSON.stringify({ sessionId })
+    const req = http.request({
+      hostname: HOST,
+      port: PORT,
+      path: '/session/end',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload),
+      },
+      timeout: TIMEOUT_MS,
+    }, (res) => {
+      let body = ''
+      res.on('data', (c) => { body += c })
+      res.on('end', () => {
+        if (res.statusCode !== 200) {
+          console.error(`[ccRecall] harvest failed ${res.statusCode}: ${sanitizeForLog(body.slice(0, 200))}`)
+          resolve()
+          return
+        }
+        try {
+          const parsed = JSON.parse(body)
+          if (Array.isArray(parsed.memoriesSaved) && parsed.memoriesSaved.length === 0) {
+            const reason = sanitizeForLog(String(parsed.reason ?? 'unknown'))
+            console.error(`[ccRecall] harvest yielded 0 memories (reason: ${reason}).`)
+          }
+        } catch {
+          // response wasn't JSON; already 200 so treat as success
+        }
+        resolve()
+      })
+    })
+    req.on('error', (err) => {
+      console.error(`[ccRecall] harvest error: ${err.message} (is the service running on :${PORT}?)`)
+      resolve()
+    })
+    req.on('timeout', () => {
+      console.error(`[ccRecall] harvest timeout after ${TIMEOUT_MS}ms`)
+      req.destroy()
+      resolve()
+    })
+    req.write(payload)
+    req.end()
+  })
+}
+
+async function main() {
+  let input
+  try {
+    const raw = await readStdin()
+    input = raw ? JSON.parse(raw) : {}
+  } catch (err) {
+    console.error(`[ccRecall] failed to parse hook input: ${err.message}`)
+    return
+  }
+
+  // 'resume' means session is continuing, not ending — skip harvest.
+  if (input.reason === 'resume') return
+
+  const sessionId = input.session_id
+  if (!sessionId) return
+
+  await postSessionEnd(sessionId)
+}
+
+main().catch((err) => {
+  console.error(`[ccRecall] unexpected error: ${err.message}`)
+})

package/hooks/session-start.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// ccRecall SessionStart hook — injects relevant memories as context at session start.
+// Wired via ~/.claude/settings.json hooks.SessionStart. Output on stdout is
+// prepended to Claude's context; errors go to stderr only.
+import http from 'node:http'
+
+const PORT = Number(process.env.CCRECALL_PORT ?? 7749)
+const HOST = '127.0.0.1'
+const TIMEOUT_MS = 2000
+const MEMORY_LIMIT = 5
+
+async function readStdin() {
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+function queryMemories(query, projectId) {
+  return new Promise((resolve) => {
+    const params = new URLSearchParams({ q: query, limit: String(MEMORY_LIMIT) })
+    if (projectId) params.set('project', projectId)
+    const url = `/memory/query?${params.toString()}`
+    const req = http.request({
+      hostname: HOST,
+      port: PORT,
+      path: url,
+      method: 'GET',
+      timeout: TIMEOUT_MS,
+    }, (res) => {
+      let body = ''
+      res.on('data', (c) => { body += c })
+      res.on('end', () => {
+        if (res.statusCode !== 200) {
+          console.error(`[ccRecall] query failed ${res.statusCode}`)
+          resolve([])
+          return
+        }
+        try {
+          const parsed = JSON.parse(body)
+          resolve(Array.isArray(parsed.memories) ? parsed.memories : [])
+        } catch {
+          resolve([])
+        }
+      })
+    })
+    req.on('error', (err) => {
+      console.error(`[ccRecall] query error: ${err.message} (is the service running on :${PORT}?)`)
+      resolve([])
+    })
+    req.on('timeout', () => {
+      console.error(`[ccRecall] query timeout after ${TIMEOUT_MS}ms`)
+      req.destroy()
+      resolve([])
+    })
+    req.end()
+  })
+}
+
+function projectNameFromCwd(cwd) {
+  if (!cwd || typeof cwd !== 'string') return ''
+  const parts = cwd.split('/').filter(Boolean)
+  return parts[parts.length - 1] ?? ''
+}
+
+// Matches Claude Code's project-directory encoding under ~/.claude/projects/
+function projectIdFromCwd(cwd) {
+  if (!cwd || typeof cwd !== 'string') return ''
+  return cwd.replace(/\//g, '-')
+}
+
+function formatMemories(memories, query) {
+  if (memories.length === 0) return ''
+  const lines = memories.map((m) => {
+    const conf = m.confidence != null && m.confidence !== 1
+      ? ` (conf ${Number(m.confidence).toFixed(2)})`
+      : ''
+    return `- ${m.content}${conf}`
+  })
+  return [
+    '[ccRecall memory recall]',
+    '',
+    ...lines,
+    '',
+    `(matched via project keyword: "${query}")`,
+  ].join('\n')
+}
+
+async function main() {
+  let input
+  try {
+    const raw = await readStdin()
+    input = raw ? JSON.parse(raw) : {}
+  } catch (err) {
+    console.error(`[ccRecall] failed to parse hook input: ${err.message}`)
+    return
+  }
+
+  // 'resume' continues an existing session; context is already there.
+  if (input.source === 'resume') return
+
+  const query = projectNameFromCwd(input.cwd)
+  if (!query) return
+  const projectId = projectIdFromCwd(input.cwd)
+
+  const memories = await queryMemories(query, projectId)
+  const text = formatMemories(memories, query)
+  if (text) process.stdout.write(text)
+}
+
+main().catch((err) => {
+  console.error(`[ccRecall] unexpected error: ${err.message}`)
+})