@hanhnd/agent-kit 1.0.28 → 1.0.30

package/dist/memory/store.js

@@ -0,0 +1,273 @@
+import Database from 'better-sqlite3';
+import * as fs from 'fs';
+import * as path from 'path';
+import { eng, removeStopwords } from 'stopword';
+export class StoreError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = 'StoreError';
+        if (cause instanceof Error)
+            this.cause = cause;
+    }
+}
+export class MemoryStore {
+    config;
+    db;
+    _vecAvailable = false;
+    constructor(dbPath, config) {
+        this.config = config;
+        fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+        this.db = this.openDatabase(dbPath);
+    }
+    openDatabase(dbPath) {
+        try {
+            const db = new Database(dbPath);
+            db.pragma('journal_mode = WAL');
+            db.pragma('busy_timeout = 5000');
+            this.loadVecExtension(db);
+            this.createSchema(db);
+            return db;
+        }
+        catch (err) {
+            console.error('[memory-store] DB open failed, recreating:', err);
+            try {
+                fs.unlinkSync(dbPath);
+            }
+            catch {
+                // ignore
+            }
+            const db = new Database(dbPath);
+            db.pragma('journal_mode = WAL');
+            db.pragma('busy_timeout = 5000');
+            this.loadVecExtension(db);
+            this.createSchema(db);
+            return db;
+        }
+    }
+    loadVecExtension(db) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const sqliteVec = require('sqlite-vec');
+            sqliteVec.load(db);
+            this._vecAvailable = true;
+        }
+        catch (err) {
+            console.warn('[memory-store] sqlite-vec unavailable, degrading to FTS5-only:', err);
+            this._vecAvailable = false;
+        }
+    }
+    createSchema(db) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS memory_chunks (
+        rowid         INTEGER PRIMARY KEY AUTOINCREMENT,
+        id            TEXT NOT NULL UNIQUE,
+        source        TEXT NOT NULL,
+        heading       TEXT NOT NULL DEFAULT '',
+        heading_level INTEGER NOT NULL DEFAULT 0,
+        content       TEXT NOT NULL,
+        line_start    INTEGER NOT NULL,
+        line_end      INTEGER NOT NULL,
+        indexed_at    INTEGER NOT NULL
+      );
+
+      CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+        source,
+        heading,
+        content,
+        content='memory_chunks',
+        content_rowid='rowid'
+      );
+
+      CREATE TRIGGER IF NOT EXISTS memory_chunks_ai
+        AFTER INSERT ON memory_chunks BEGIN
+          INSERT INTO memory_fts(rowid, source, heading, content)
+            VALUES (new.rowid, new.source, new.heading, new.content);
+        END;
+
+      CREATE TRIGGER IF NOT EXISTS memory_chunks_ad
+        AFTER DELETE ON memory_chunks BEGIN
+          INSERT INTO memory_fts(memory_fts, rowid, source, heading, content)
+            VALUES ('delete', old.rowid, old.source, old.heading, old.content);
+        END;
+    `);
+        if (this._vecAvailable) {
+            try {
+                db.exec(`
+          CREATE VIRTUAL TABLE IF NOT EXISTS memory_vec USING vec0(
+            embedding FLOAT[${this.config.vectorDimension}]
+          );
+        `);
+            }
+            catch (err) {
+                console.warn('[memory-store] Failed to create memory_vec, disabling vector search:', err);
+                this._vecAvailable = false;
+            }
+        }
+    }
+    upsert(chunks, embeddings) {
+        const insertChunk = this.db.prepare(`
+      INSERT OR REPLACE INTO memory_chunks
+        (id, source, heading, heading_level, content, line_start, line_end, indexed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        let insertVec = null;
+        if (this._vecAvailable) {
+            insertVec = this.db.prepare(`INSERT OR REPLACE INTO memory_vec (rowid, embedding) VALUES (?, ?)`);
+        }
+        const upsertAll = this.db.transaction(() => {
+            for (let i = 0; i < chunks.length; i++) {
+                const chunk = chunks[i];
+                try {
+                    // Delete existing row first to get correct rowid
+                    this.db.prepare(`DELETE FROM memory_chunks WHERE id = ?`).run(chunk.id);
+                    const info = insertChunk.run(chunk.id, chunk.source, chunk.heading, chunk.headingLevel, chunk.content, chunk.lineStart, chunk.lineEnd, Date.now());
+                    if (insertVec && embeddings[i] && info.lastInsertRowid) {
+                        const rowid = Number(info.lastInsertRowid);
+                        const emb = embeddings[i];
+                        const buf = Buffer.from(emb.buffer, emb.byteOffset, emb.byteLength);
+                        insertVec.run(rowid, buf);
+                    }
+                }
+                catch (err) {
+                    console.warn(`[memory-store] Failed to upsert chunk ${chunk.id}:`, err);
+                }
+            }
+        });
+        try {
+            upsertAll();
+        }
+        catch (err) {
+            throw new StoreError('Full batch upsert failed', err);
+        }
+    }
+    hashesBySource(source) {
+        const rows = this.db
+            .prepare(`SELECT id FROM memory_chunks WHERE source = ?`)
+            .all(source);
+        return new Set(rows.map((r) => r.id));
+    }
+    indexedSources() {
+        const rows = this.db
+            .prepare(`SELECT DISTINCT source FROM memory_chunks`)
+            .all();
+        return rows.map((r) => r.source);
+    }
+    deleteBySource(source) {
+        const rows = this.db
+            .prepare(`SELECT rowid FROM memory_chunks WHERE source = ?`)
+            .all(source);
+        const deleteAll = this.db.transaction(() => {
+            if (this._vecAvailable && rows.length > 0) {
+                const placeholders = rows.map(() => '?').join(', ');
+                this.db
+                    .prepare(`DELETE FROM memory_vec WHERE rowid IN (${placeholders})`)
+                    .run(...rows.map((r) => r.rowid));
+            }
+            this.db.prepare(`DELETE FROM memory_chunks WHERE source = ?`).run(source);
+        });
+        deleteAll();
+    }
+    deleteByIds(ids) {
+        if (ids.length === 0)
+            return;
+        const placeholders = ids.map(() => '?').join(', ');
+        const rows = this.db
+            .prepare(`SELECT rowid FROM memory_chunks WHERE id IN (${placeholders})`)
+            .all(...ids);
+        const deleteAll = this.db.transaction(() => {
+            if (this._vecAvailable && rows.length > 0) {
+                const rPlaceholders = rows.map(() => '?').join(', ');
+                this.db
+                    .prepare(`DELETE FROM memory_vec WHERE rowid IN (${rPlaceholders})`)
+                    .run(...rows.map((r) => r.rowid));
+            }
+            this.db.prepare(`DELETE FROM memory_chunks WHERE id IN (${placeholders})`).run(...ids);
+        });
+        deleteAll();
+    }
+    searchDense(embedding, limit) {
+        if (!this._vecAvailable)
+            return [];
+        try {
+            const buf = Buffer.from(embedding.buffer);
+            const rows = this.db
+                .prepare(`SELECT mc.id, mv.distance
+           FROM memory_vec mv
+           JOIN memory_chunks mc ON mc.rowid = mv.rowid
+           WHERE mv.embedding MATCH ? AND k = ?
+           ORDER BY mv.distance`)
+                .all(buf, limit);
+            return rows.map((r) => ({
+                id: r.id,
+                score: Math.max(0, 1 - r.distance),
+            }));
+        }
+        catch (err) {
+            console.warn('[memory-store] Dense search failed:', err);
+            return [];
+        }
+    }
+    searchBm25(query, limit) {
+        if (!query.trim())
+            return [];
+        const tokens = query
+            .trim()
+            .split(/\s+/)
+            .map((t) => t.replace(/[^a-zA-Z0-9_]/g, '').toLowerCase())
+            .filter((t) => t.length > 1);
+        const ftsQuery = removeStopwords(tokens, eng)
+            .map((t) => `${t.replace(/s$/, '')}*`)
+            .join(' OR ');
+        if (!ftsQuery)
+            return [];
+        try {
+            const rows = this.db
+                .prepare(`SELECT mc.id, bm25(memory_fts, 0.2, 2.0, 5.0) AS rank
+           FROM memory_fts
+           JOIN memory_chunks mc ON mc.rowid = memory_fts.rowid
+           WHERE memory_fts MATCH ?
+           ORDER BY rank
+           LIMIT ?`)
+                .all(ftsQuery, limit);
+            if (rows.length === 0)
+                return [];
+            // BM25 rank is negative in SQLite FTS5 (lower = more relevant)
+            const ranks = rows.map((r) => r.rank);
+            const minRank = Math.min(...ranks);
+            const maxRank = Math.max(...ranks);
+            const range = maxRank - minRank;
+            return rows.map((r) => ({
+                id: r.id,
+                score: range > 0 ? (maxRank - r.rank) / range : 1,
+            }));
+        }
+        catch (err) {
+            console.warn('[memory-store] BM25 search failed:', err);
+            return [];
+        }
+    }
+    getChunksByIds(ids) {
+        if (ids.length === 0)
+            return [];
+        const placeholders = ids.map(() => '?').join(', ');
+        const rows = this.db
+            .prepare(`SELECT id, source, heading, heading_level, content, line_start, line_end
+         FROM memory_chunks WHERE id IN (${placeholders})`)
+            .all(...ids);
+        return rows.map((r) => ({
+            id: r.id,
+            source: r.source,
+            heading: r.heading,
+            headingLevel: r.heading_level,
+            content: r.content,
+            lineStart: r.line_start,
+            lineEnd: r.line_end,
+        }));
+    }
+    get vecAvailable() {
+        return this._vecAvailable;
+    }
+    close() {
+        this.db.close();
+    }
+}

package/dist/memory/types.d.ts

@@ -0,0 +1,30 @@
+export interface MemoryChunk {
+    id: string;
+    source: string;
+    heading: string;
+    headingLevel: number;
+    content: string;
+    lineStart: number;
+    lineEnd: number;
+}
+export interface SearchResult {
+    chunk: MemoryChunk;
+    score: number;
+    retriever: 'dense' | 'bm25' | 'both';
+    contentSource: 'file' | 'fallback';
+}
+export interface MemoryConfig {
+    enabled: boolean;
+    wikiDir: string;
+    topK: number;
+    chunkSize: number;
+    overlapLines: number;
+    embeddingModel: string;
+    vectorDimension: number;
+}
+export interface IndexStats {
+    indexed: number;
+    deleted: number;
+    skipped: number;
+}
+export declare const DEFAULT_MEMORY_CONFIG: MemoryConfig;

package/dist/memory/types.js

@@ -0,0 +1,9 @@
+export const DEFAULT_MEMORY_CONFIG = {
+    enabled: false,
+    wikiDir: '',
+    topK: 5,
+    chunkSize: 1500,
+    overlapLines: 2,
+    embeddingModel: 'Xenova/bge-small-en-v1.5',
+    vectorDimension: 384,
+};

package/dist/tools/__tests__/memory.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/__tests__/memory.test.js

@@ -0,0 +1,185 @@
+import * as assert from 'node:assert/strict';
+import { describe, test } from 'node:test';
+import { resolveMemoryConfig } from '../config.js';
+import { registerMemoryToolHandlers } from '../memory.js';
+// Minimal McpServer stub that captures tool registrations
+function makeMockServer() {
+    const tools = new Map();
+    const server = {
+        tool(name, _desc, _schema, handler) {
+            tools.set(name, handler);
+        },
+    };
+    return { server, tools };
+}
+function makeChunk(overrides = {}) {
+    return {
+        id: 'test-id-abc123',
+        source: '2024-01-01.md',
+        heading: 'My Section',
+        headingLevel: 2,
+        content: 'This is the chunk content.',
+        lineStart: 1,
+        lineEnd: 5,
+        ...overrides,
+    };
+}
+const BASE_CONFIG = {
+    enabled: true,
+    wikiDir: '/tmp/wiki',
+    topK: 5,
+    chunkSize: 1500,
+    overlapLines: 2,
+    embeddingModel: 'Xenova/bge-small-en-v1.5',
+    vectorDimension: 384,
+};
+function makeIndexerStub(overrides = {}) {
+    return {
+        search: overrides.search ?? (async () => []),
+        save: overrides.save ?? (async () => ({ indexed: 1, deleted: 0, skipped: 0 })),
+    };
+}
+function makeStoreStub(vecAvailable) {
+    return { vecAvailable };
+}
+function extractText(result) {
+    const r = result;
+    return r.content[0]?.text ?? '';
+}
+describe('kit_memory_search', () => {
+    test('returns formatted full content and display source when results exist', async () => {
+        const chunk = makeChunk({ content: 'Important memory content', source: 'compiled/entities/foo.md' });
+        const searchResult = { chunk, score: 0.85, retriever: 'bm25', contentSource: 'file' };
+        const indexer = makeIndexerStub({ search: async () => [searchResult] });
+        const store = makeStoreStub(true);
+        const { server, tools } = makeMockServer();
+        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        const result = await tools.get('kit_memory_search')({ query: 'test query' });
+        const text = extractText(result);
+        assert.ok(text.includes('Important memory content'), 'Result must include chunk content');
+        assert.ok(text.includes('### entities/foo.md (score: 0.850)'), 'Result must include display source and score');
+        assert.ok(!text.includes('compiled/entities/foo.md'), 'Result must strip compiled/ prefix');
+        assert.ok(!text.includes('My Section'), 'Result must not include chunk heading as the block title');
+    });
+    test('returns "no memories" message when results are empty', async () => {
+        const indexer = makeIndexerStub({ search: async () => [] });
+        const store = makeStoreStub(true);
+        const { server, tools } = makeMockServer();
+        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        const result = await tools.get('kit_memory_search')({ query: 'nothing here' });
+        const text = extractText(result);
+        assert.ok(text.toLowerCase().includes('no memories') || text.includes('No memories'), `Expected "no memories" message, got: ${text.slice(0, 100)}`);
+    });
+    test('prepends degraded warning when vecAvailable is false and no results', async () => {
+        const indexer = makeIndexerStub({ search: async () => [] });
+        const store = makeStoreStub(false);
+        const { server, tools } = makeMockServer();
+        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        const result = await tools.get('kit_memory_search')({ query: 'test' });
+        const text = extractText(result);
+        assert.ok(text.includes('Vector search unavailable') || text.includes('keyword-only'), `Expected degraded warning in: ${text.slice(0, 200)}`);
+    });
+    test('prepends degraded warning when vecAvailable is false with results', async () => {
+        const chunk = makeChunk({ content: 'Found content', source: 'test.md' });
+        const searchResult = { chunk, score: 0.5, retriever: 'bm25', contentSource: 'file' };
+        const indexer = makeIndexerStub({ search: async () => [searchResult] });
+        const store = makeStoreStub(false);
+        const { server, tools } = makeMockServer();
+        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        const result = await tools.get('kit_memory_search')({ query: 'test' });
+        const text = extractText(result);
+        assert.ok(text.includes('Vector search unavailable') || text.includes('keyword-only'), `Expected degraded warning with results in: ${text.slice(0, 200)}`);
+        assert.ok(text.includes('Found content'), 'Result must still contain chunk content');
+    });
+    test('prepends source-unavailable warning for fallback results', async () => {
+        const chunk = makeChunk({ content: 'Stored chunk only', source: 'compiled/entities/foo.md' });
+        const searchResult = { chunk, score: 0.5, retriever: 'bm25', contentSource: 'fallback' };
+        const indexer = makeIndexerStub({ search: async () => [searchResult] });
+        const store = makeStoreStub(true);
+        const { server, tools } = makeMockServer();
+        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        const result = await tools.get('kit_memory_search')({ query: 'test' });
+        const text = extractText(result);
+        assert.ok(text.includes('Source file unavailable'), `Expected fallback warning in: ${text}`);
+        assert.ok(text.includes('Stored chunk only'), 'Result must include fallback chunk content');
+    });
+    test('uses top_k parameter when provided', async () => {
+        let capturedTopK;
+        const indexer = makeIndexerStub({
+            search: async (_q, topK) => {
+                capturedTopK = topK;
+                return [];
+            },
+        });
+        const store = makeStoreStub(true);
+        const { server, tools } = makeMockServer();
+        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        await tools.get('kit_memory_search')({ query: 'test', top_k: 3 });
+        assert.equal(capturedTopK, 3);
+    });
+    test('falls back to config.topK when top_k is not provided', async () => {
+        let capturedTopK;
+        const indexer = makeIndexerStub({
+            search: async (_q, topK) => {
+                capturedTopK = topK;
+                return [];
+            },
+        });
+        const store = makeStoreStub(true);
+        const { server, tools } = makeMockServer();
+        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        await tools.get('kit_memory_search')({ query: 'test' });
+        assert.equal(capturedTopK, BASE_CONFIG.topK);
+    });
+    test('returns error message when indexer.search throws', async () => {
+        const indexer = makeIndexerStub({
+            search: async () => { throw new Error('search exploded'); },
+        });
+        const store = makeStoreStub(true);
+        const { server, tools } = makeMockServer();
+        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        const result = await tools.get('kit_memory_search')({ query: 'test' });
+        const text = extractText(result);
+        assert.ok(text.includes('kit_memory_search failed'), `Expected error prefix, got: ${text}`);
+        assert.ok(text.includes('search exploded'), `Expected error message, got: ${text}`);
+    });
+});
+describe('kit_memory_save', () => {
+    test('returns saved:true and queued-for-compile status on success', async () => {
+        const indexer = makeIndexerStub({
+            save: async () => ({ indexed: 0, deleted: 0, skipped: 0 }),
+        });
+        const store = makeStoreStub(true);
+        const { server, tools } = makeMockServer();
+        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        const result = await tools.get('kit_memory_save')({ content: 'Some important note' });
+        const text = extractText(result);
+        const parsed = JSON.parse(text);
+        assert.equal(parsed.saved, true);
+        assert.equal(parsed.queued_for_compile, true);
+        assert.equal(parsed.message, 'Saved to wiki/raw — will be indexed after next /wiki compile');
+    });
+    test('returns saved:false and error message when indexer.save throws', async () => {
+        const indexer = makeIndexerStub({
+            save: async () => { throw new Error('disk full'); },
+        });
+        const store = makeStoreStub(true);
+        const { server, tools } = makeMockServer();
+        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        const result = await tools.get('kit_memory_save')({ content: 'note' });
+        const text = extractText(result);
+        const parsed = JSON.parse(text);
+        assert.equal(parsed.saved, false);
+        assert.ok(parsed.error.includes('disk full'), `Expected "disk full" in error, got: ${parsed.error}`);
+    });
+});
+describe('resolveMemoryConfig', () => {
+    test('defaults wikiDir under .agent-kit', () => {
+        const config = resolveMemoryConfig({ memory: {} }, '/repo');
+        assert.equal(config.wikiDir, '/repo/.agent-kit/wiki');
+    });
+    test('uses explicit wikiDir override', () => {
+        const config = resolveMemoryConfig({ memory: { wikiDir: '/custom/wiki' } }, '/repo');
+        assert.equal(config.wikiDir, '/custom/wiki');
+    });
+});

package/dist/tools/config.d.ts

@@ -2,6 +2,7 @@
  * Configuration utilities
  * Shared configuration constants and loaders
  */
+import { type MemoryConfig } from '../memory/types.js';
 /**
  * Default file extensions - expanded to support more languages
  * Used by kit_get_project_context and other tools
@@ -12,8 +13,14 @@ export declare const DEFAULT_EXTENSIONS: string[];
  */
 export interface ProjectSettings {
     fileExtensions?: string[];
+    memory?: Partial<MemoryConfig>;
     [key: string]: unknown;
 }
+export { MemoryConfig };
+/**
+ * Merge DEFAULT_MEMORY_CONFIG with settings.memory; resolve wikiDir when not explicitly set.
+ */
+export declare function resolveMemoryConfig(settings: ProjectSettings, workspaceRoot: string): MemoryConfig;
 /**
  * Get file extensions - from settings.json or defaults
  * Allows project-specific customization

package/dist/tools/config.js

@@ -4,6 +4,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { DEFAULT_MEMORY_CONFIG } from '../memory/types.js';
 /**
  * Default file extensions - expanded to support more languages
  * Used by kit_get_project_context and other tools
@@ -32,6 +33,20 @@ export const DEFAULT_EXTENSIONS = [
     '.yml', // Config files
     '.md', // Documentation
 ];
+/**
+ * Merge DEFAULT_MEMORY_CONFIG with settings.memory; resolve wikiDir when not explicitly set.
+ */
+export function resolveMemoryConfig(settings, workspaceRoot) {
+    const override = settings.memory ?? {};
+    return {
+        ...DEFAULT_MEMORY_CONFIG,
+        ...override,
+        enabled: override.enabled ?? DEFAULT_MEMORY_CONFIG.enabled,
+        wikiDir: typeof override.wikiDir === 'string' && override.wikiDir.length > 0
+            ? override.wikiDir
+            : path.join(workspaceRoot, '.agent-kit', 'wiki'),
+    };
+}
 /**
  * Get file extensions - from settings.json or defaults
  * Allows project-specific customization

package/dist/tools/memory.d.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { MemoryIndexer } from '../memory/indexer.js';
+import { MemoryStore } from '../memory/store.js';
+import type { MemoryConfig } from '../memory/types.js';
+import { type ProjectSettings } from './config.js';
+/**
+ * Registers tool handlers onto an already-constructed indexer/store pair.
+ * Exported for unit testing with mocks.
+ */
+export declare function registerMemoryToolHandlers(server: McpServer, indexer: MemoryIndexer, store: MemoryStore, config: MemoryConfig): void;
+/**
+ * Initializes the memory subsystem and registers all memory tools.
+ * Returns the MemoryIndexer so the caller can fire startupIndex() after server.connect().
+ * Returns null when memory is disabled (settings.memory.enabled !== true).
+ */
+export declare function registerMemoryTools(server: McpServer, settings: ProjectSettings, workspaceRoot: string): MemoryIndexer | null;

package/dist/tools/memory.js

@@ -0,0 +1,75 @@
+import * as path from 'path';
+import { z } from 'zod';
+import { Embedder } from '../memory/embedder.js';
+import { MemoryIndexer } from '../memory/indexer.js';
+import { MemoryStore } from '../memory/store.js';
+import { mcpJson, mcpText } from '../utils/utils.js';
+import { resolveMemoryConfig } from './config.js';
+/**
+ * Registers tool handlers onto an already-constructed indexer/store pair.
+ * Exported for unit testing with mocks.
+ */
+export function registerMemoryToolHandlers(server, indexer, store, config) {
+    server.tool('kit_memory_search', 'Search persistent memory for context relevant to the current question. Returns semantically relevant results using hybrid dense+BM25+RRF search.', {
+        query: z.string().min(1).describe('Search query'),
+        top_k: z.number().int().positive().optional().describe('Number of results to return'),
+    }, async ({ query, top_k }) => {
+        try {
+            const results = await indexer.search(query, top_k ?? config.topK);
+            if (results.length === 0) {
+                const degradedNote = !store.vecAvailable
+                    ? '⚠️ Vector search unavailable — showing keyword-only results.\n\n'
+                    : '';
+                return mcpText(`${degradedNote}No memories found for query: "${query}"`);
+            }
+            const degradedNote = !store.vecAvailable
+                ? '⚠️ Vector search unavailable — showing keyword-only results.\n\n'
+                : '';
+            const formatted = results
+                .map((r) => {
+                const displaySource = r.chunk.source.replace(/^compiled\//, '');
+                const content = r.contentSource === 'fallback'
+                    ? `⚠️ Source file unavailable — showing matched chunk only:\n${r.chunk.content}`
+                    : r.chunk.content;
+                return `### ${displaySource} (score: ${r.score.toFixed(3)})\n${content}`;
+            })
+                .join('\n\n---\n\n');
+            return mcpText(`${degradedNote}${formatted}`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return mcpText(`kit_memory_search failed: ${message}`);
+        }
+    });
+    server.tool('kit_memory_save', 'Save content to wiki/raw for inclusion after the next /wiki compile.', {
+        content: z.string().min(1).describe('Content to save to memory'),
+    }, async ({ content }) => {
+        try {
+            await indexer.save(content);
+            return mcpJson({
+                saved: true,
+                queued_for_compile: true,
+                message: 'Saved to wiki/raw — will be indexed after next /wiki compile',
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return mcpJson({ saved: false, error: message });
+        }
+    });
+}
+/**
+ * Initializes the memory subsystem and registers all memory tools.
+ * Returns the MemoryIndexer so the caller can fire startupIndex() after server.connect().
+ * Returns null when memory is disabled (settings.memory.enabled !== true).
+ */
+export function registerMemoryTools(server, settings, workspaceRoot) {
+    if (settings.memory?.enabled !== true)
+        return null;
+    const config = resolveMemoryConfig(settings, workspaceRoot);
+    const store = new MemoryStore(path.join(config.wikiDir, 'index.db'), config);
+    const embedder = new Embedder(config.embeddingModel);
+    const indexer = new MemoryIndexer(store, embedder, config);
+    registerMemoryToolHandlers(server, indexer, store, config);
+    return indexer;
+}

package/dist/utils/utils.js

@@ -1,8 +1,10 @@
 export function getWorkspaceRoot() {
     return (process.env.WORKSPACE_DIR ||
-        process.env.CODEX_WORKSPACE ||
+        process.env.CLAUDE_PROJECT_DIR ||
         process.env.CODEX_PROJECT_DIR ||
+        process.env.GEMINI_PROJECT_DIR ||
         process.env.CLAUDE_WORKSPACE ||
+        process.env.CODEX_WORKSPACE ||
         process.env.GEMINI_WORKSPACE ||
         process.env.INIT_CWD ||
         process.env.PWD ||