kimi-code-memory-mcp-server 0.1.0 → 0.1.2

package/dist/dao/index-reconciler.js

@@ -0,0 +1,162 @@
+/**
+ * Index reconciler: directory scanning, structure hashing, and full rebuild.
+ */
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { safeParseFile } from '../utils/file-helpers.js';
+import { toTitle } from '../utils/validation.js';
+import { FALLBACK_FOLDER_COMMENTS } from './constants.js';
+export class IndexReconciler {
+    storeRoot;
+    store;
+    constructor(storeRoot, store) {
+        this.storeRoot = storeRoot;
+        this.store = store;
+    }
+    computeStructureHash() {
+        const paths = [];
+        const scan = (dir, relativePrefix) => {
+            if (!fs.existsSync(dir))
+                return false;
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            let hasContent = false;
+            for (const entry of entries) {
+                if (entry.name.startsWith('.'))
+                    continue;
+                const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
+                if (entry.isDirectory()) {
+                    const childHasContent = scan(path.join(dir, entry.name), relativePath);
+                    if (childHasContent)
+                        hasContent = true;
+                }
+                else if (entry.isFile() && entry.name.endsWith('.md')) {
+                    const fullPath = path.join(dir, entry.name);
+                    const stats = fs.statSync(fullPath);
+                    paths.push(`${relativePath}:${stats.mtime.toISOString()}`);
+                    hasContent = true;
+                }
+            }
+            if (!hasContent && relativePrefix) {
+                paths.push(`${relativePrefix}/`);
+            }
+            return hasContent;
+        };
+        scan(path.join(this.storeRoot, 'memory'), 'memory');
+        scan(path.join(this.storeRoot, 'notes'), 'notes');
+        scan(path.join(this.storeRoot, 'essence'), 'essence');
+        paths.sort();
+        const content = paths.join('\n');
+        return content ? crypto.createHash('md5').update(content).digest('hex') : '';
+    }
+    buildEntryValueFromFile(filePath) {
+        const parsed = safeParseFile(filePath);
+        const key = path.basename(filePath, '.md');
+        const title = String(parsed?.frontmatter?.title || toTitle(key));
+        const tags = Array.isArray(parsed?.frontmatter?.tags)
+            ? parsed.frontmatter.tags
+            : [];
+        return { title, tags };
+    }
+    reconcileIndex(options = {}) {
+        const index = this.store.getIndex();
+        const currentHash = this.computeStructureHash();
+        if (currentHash &&
+            currentHash === index.meta.structureHash &&
+            Object.keys(index.index).length > 0) {
+            let patched = false;
+            if (options.folderComments) {
+                for (let folderPath of Object.keys(options.folderComments)) {
+                    const comment = options.folderComments[folderPath];
+                    if (!folderPath.endsWith('/'))
+                        folderPath += '/';
+                    index.index[folderPath] = { comment };
+                    patched = true;
+                }
+            }
+            if (patched) {
+                this.store.saveIndex(index);
+            }
+            return {
+                synced: true,
+                skipped: true,
+                structureHash: currentHash,
+                report: {
+                    scannedFiles: 0,
+                    addedEntries: 0,
+                    removedEntries: 0,
+                    updatedEntries: 0,
+                    addedFolders: 0,
+                },
+            };
+        }
+        const report = {
+            scannedFiles: 0,
+            addedEntries: 0,
+            removedEntries: 0,
+            updatedEntries: 0,
+            addedFolders: 0,
+        };
+        const diskFiles = new Set();
+        const scanDir = (dir, relativePrefix) => {
+            if (!fs.existsSync(dir))
+                return;
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.name.startsWith('.'))
+                    continue;
+                const relativePath = relativePrefix ? `${relativePrefix}/${entry.name}` : entry.name;
+                if (entry.isDirectory()) {
+                    scanDir(path.join(dir, entry.name), relativePath);
+                }
+                else if (entry.isFile() && entry.name.endsWith('.md')) {
+                    diskFiles.add(relativePath);
+                    report.scannedFiles++;
+                    const value = this.buildEntryValueFromFile(path.join(this.storeRoot, relativePath));
+                    const existing = index.index[relativePath];
+                    if (!existing) {
+                        index.index[relativePath] = value;
+                        report.addedEntries++;
+                    }
+                    else if (existing.title !== value.title ||
+                        JSON.stringify(existing.tags) !== JSON.stringify(value.tags)) {
+                        index.index[relativePath] = value;
+                        report.updatedEntries++;
+                    }
+                    const dirPath = path.dirname(relativePath);
+                    const parts = dirPath.split('/').filter(Boolean);
+                    let current = '';
+                    for (const part of parts) {
+                        current = current ? `${current}/${part}` : part;
+                        const folderPath = `${current}/`;
+                        if (!(folderPath in index.index)) {
+                            index.index[folderPath] = { comment: FALLBACK_FOLDER_COMMENTS[part] || '' };
+                            report.addedFolders++;
+                        }
+                    }
+                }
+            }
+        };
+        scanDir(path.join(this.storeRoot, 'memory'), 'memory');
+        scanDir(path.join(this.storeRoot, 'notes'), 'notes');
+        scanDir(path.join(this.storeRoot, 'essence'), 'essence');
+        for (const key of Object.keys(index.index)) {
+            if (key.endsWith('.md') && !diskFiles.has(key)) {
+                delete index.index[key];
+                report.removedEntries++;
+            }
+        }
+        if (options.folderComments) {
+            for (let folderPath of Object.keys(options.folderComments)) {
+                const comment = options.folderComments[folderPath];
+                if (!folderPath.endsWith('/'))
+                    folderPath += '/';
+                index.index[folderPath] = { comment };
+            }
+        }
+        index.meta.structureHash = currentHash;
+        this.store.saveIndex(index);
+        return { synced: true, skipped: false, structureHash: currentHash, report };
+    }
+}
+//# sourceMappingURL=index-reconciler.js.map

package/dist/dao/index-reconciler.js.map

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

package/dist/dao/index-store.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Low-level index.json storage: load, save, in-memory cache, backup, migration.
+ */
+import type { IndexData } from './constants.js';
+export declare class IndexStore {
+    storeRoot: string;
+    backupRoot: string;
+    private indexCache;
+    private mutex;
+    constructor(storeRoot: string, options?: {
+        backupRoot?: string;
+    });
+    get indexPath(): string;
+    loadIndex(): IndexData;
+    saveIndex(index: IndexData): void;
+    getIndex(): IndexData;
+    getBackupId(): string;
+    backupIndex(backupId: string): {
+        backedUp: boolean;
+        backupPath?: string;
+    };
+    migrateV1ToV3(v1: {
+        entries?: Record<string, {
+            folder?: string;
+            key?: string;
+            title?: string;
+            tags?: string[];
+        }>;
+    }): IndexData;
+    runExclusive<T>(fn: () => T): Promise<T>;
+}

package/dist/dao/index-store.js

@@ -0,0 +1,128 @@
+/**
+ * Low-level index.json storage: load, save, in-memory cache, backup, migration.
+ */
+import fs from 'fs';
+import path from 'path';
+import { Mutex } from '../utils/mutex.js';
+import { toTitle } from '../utils/validation.js';
+import { FALLBACK_FOLDER_COMMENTS } from './constants.js';
+function createEmptyIndex() {
+    return {
+        version: '3-kv',
+        meta: { lastSyncAt: null, structureHash: null },
+        index: {},
+    };
+}
+export class IndexStore {
+    storeRoot;
+    backupRoot;
+    indexCache;
+    mutex;
+    constructor(storeRoot, options = {}) {
+        this.storeRoot = storeRoot;
+        this.backupRoot = options.backupRoot || path.join(storeRoot, '..', 'backup');
+        this.indexCache = null;
+        this.mutex = new Mutex();
+    }
+    get indexPath() {
+        return path.join(this.storeRoot, 'index.json');
+    }
+    loadIndex() {
+        if (this.indexCache)
+            return this.indexCache;
+        if (!fs.existsSync(this.indexPath)) {
+            this.indexCache = createEmptyIndex();
+            return this.indexCache;
+        }
+        try {
+            const text = fs.readFileSync(this.indexPath, 'utf8');
+            const parsed = JSON.parse(text);
+            if (parsed &&
+                typeof parsed === 'object' &&
+                parsed.version === '3-kv' &&
+                typeof parsed.index === 'object') {
+                this.indexCache = parsed;
+                return this.indexCache;
+            }
+            if (parsed &&
+                typeof parsed === 'object' &&
+                parsed.version === 1 &&
+                typeof parsed.entries === 'object') {
+                const backupId = this.getBackupId();
+                this.backupIndex(backupId);
+                this.indexCache = this.migrateV1ToV3(parsed);
+                this.saveIndex(this.indexCache);
+                return this.indexCache;
+            }
+        }
+        catch {
+            // Corrupt index: fall through to empty index.
+        }
+        this.indexCache = createEmptyIndex();
+        return this.indexCache;
+    }
+    saveIndex(index) {
+        index.meta.lastSyncAt = new Date().toISOString();
+        const tmpPath = this.indexPath + '.tmp';
+        fs.writeFileSync(tmpPath, JSON.stringify(index, null, 2), 'utf8');
+        fs.renameSync(tmpPath, this.indexPath);
+        this.indexCache = index;
+    }
+    getIndex() {
+        return this.loadIndex();
+    }
+    getBackupId() {
+        const now = new Date();
+        const yy = String(now.getFullYear()).slice(2);
+        const mm = String(now.getMonth() + 1).padStart(2, '0');
+        const dd = String(now.getDate()).padStart(2, '0');
+        const yymmdd = `${yy}${mm}${dd}`;
+        let seq = 1;
+        while (fs.existsSync(path.join(this.backupRoot, `${yymmdd}_${String(seq).padStart(2, '0')}`))) {
+            seq++;
+        }
+        return `${yymmdd}_${String(seq).padStart(2, '0')}`;
+    }
+    backupIndex(backupId) {
+        if (!fs.existsSync(this.indexPath))
+            return { backedUp: false };
+        const backupPath = path.join(this.backupRoot, backupId);
+        fs.mkdirSync(backupPath, { recursive: true });
+        const dest = path.join(backupPath, 'index.json');
+        fs.copyFileSync(this.indexPath, dest);
+        return { backedUp: true, backupPath: dest };
+    }
+    migrateV1ToV3(v1) {
+        const v3 = createEmptyIndex();
+        const entries = v1.entries || {};
+        for (const id of Object.keys(entries)) {
+            const e = entries[id];
+            if (!e || !e.folder || !e.key)
+                continue;
+            const relativePath = `${e.folder}/${e.key}.md`;
+            v3.index[relativePath] = {
+                title: e.title || toTitle(e.key),
+                tags: Array.isArray(e.tags) ? e.tags : [],
+            };
+        }
+        for (const key of Object.keys(v3.index)) {
+            if (!key.endsWith('.md'))
+                continue;
+            const dir = path.dirname(key);
+            const parts = dir.split('/').filter(Boolean);
+            let current = '';
+            for (const part of parts) {
+                current = current ? `${current}/${part}` : part;
+                const folderPath = `${current}/`;
+                if (!v3.index[folderPath]) {
+                    v3.index[folderPath] = { comment: FALLBACK_FOLDER_COMMENTS[part] || '' };
+                }
+            }
+        }
+        return v3;
+    }
+    async runExclusive(fn) {
+        return this.mutex.runExclusive(fn);
+    }
+}
+//# sourceMappingURL=index-store.js.map

package/dist/dao/index-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-store.js","sourceRoot":"","sources":["../../src/dao/index-store.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,SAAS,gBAAgB;IACvB,OAAO;QACL,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;QAC/C,KAAK,EAAE,EAAE;KACV,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,UAAU;IACrB,SAAS,CAAS;IAClB,UAAU,CAAS;IACX,UAAU,CAAmB;IAC7B,KAAK,CAAQ;IAErB,YAAY,SAAiB,EAAE,UAAmC,EAAE;QAClE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC7E,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACjD,CAAC;IAED,SAAS;QACP,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC,UAAU,CAAC;QAE5C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,IAAI,CAAC,UAAU,GAAG,gBAAgB,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC,UAAU,CAAC;QACzB,CAAC;QAED,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YACrD,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAEzC,IACE,MAAM;gBACN,OAAO,MAAM,KAAK,QAAQ;gBACzB,MAAgC,CAAC,OAAO,KAAK,MAAM;gBACpD,OAAQ,MAA8B,CAAC,KAAK,KAAK,QAAQ,EACzD,CAAC;gBACD,IAAI,CAAC,UAAU,GAAG,MAAmB,CAAC;gBACtC,OAAO,IAAI,CAAC,UAAU,CAAC;YACzB,CAAC;YAED,IACE,MAAM;gBACN,OAAO,MAAM,KAAK,QAAQ;gBACzB,MAAgC,CAAC,OAAO,KAAK,CAAC;gBAC/C,OAAQ,MAAgC,CAAC,OAAO,KAAK,QAAQ,EAC7D,CAAC;gBACD,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;gBACpC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;gBAC3B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,aAAa,CAClC,MAKC,CACF,CAAC;gBACF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;gBAChC,OAAO,IAAI,CAAC,UAAU,CAAC;YACzB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,8CAA8C;QAChD,CAAC;QAED,IAAI,CAAC,UAAU,GAAG,gBAAgB,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,SAAS,CAAC,KAAgB;QACxB,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACjD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC;QACxC,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QAClE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IAC1B,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;IAC1B,CAAC;IAED,WAAW;QACT,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC9C,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACvD,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC;QACjC,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,OAAO,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,MAAM,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YAC9F,GAAG,EAAE,CAAC;QACR,CAAC;QACD,OAAO,GAAG,MAAM,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IACrD,CAAC;IAED,WAAW,CAAC,QAAgB;QAC1B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QAC/D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QACxD,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QACjD,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACtC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC9C,CAAC;IAED,aAAa,CAAC,EAEb;QACC,MAAM,EAAE,GAAG,gBAAgB,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC;QACjC,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,MAAM,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC;YACtB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG;gBAAE,SAAS;YACxC,MAAM,YAAY,GAAG,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC;YAC/C,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG;gBACvB,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;gBAChC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;aAC1C,CAAC;QACJ,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,SAAS;YACnC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC9B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC7C,IAAI,OAAO,GAAG,EAAE,CAAC;YACjB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;gBAChD,MAAM,UAAU,GAAG,GAAG,OAAO,GAAG,CAAC;gBACjC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;oBAC1B,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,wBAAwB,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC3E,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,KAAK,CAAC,YAAY,CAAI,EAAW;QAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC;CACF"}

package/dist/dao/index.d.ts

@@ -3,48 +3,28 @@
  *
  * File layer is the source of truth; index.json is a rebuildable cache of
  * metadata (title, tags, folder comments).
+ *
+ * IndexDao is a thin facade over IndexStore, IndexReconciler, IndexCatalog, and
+ * MemoryIndexTreeRenderer.
  */
-export interface IndexEntry {
-    title?: string;
-    tags?: string[];
-    comment?: string;
-}
-export interface IndexData {
-    version: string;
-    meta: {
-        lastSyncAt: string | null;
-        structureHash: string | null;
-    };
-    index: Record<string, IndexEntry>;
-}
-export interface ReconcileOptions {
-    folderComments?: Record<string, string>;
-}
-export interface ReconcileReport {
-    scannedFiles: number;
-    addedEntries: number;
-    removedEntries: number;
-    updatedEntries: number;
-    addedFolders: number;
-}
-export interface ReconcileResult {
-    synced: boolean;
-    skipped: boolean;
-    structureHash: string;
-    report: ReconcileReport;
-}
+import type { IndexData, IndexEntry, ReconcileOptions, ReconcileResult } from './constants.js';
+import { type TreeNode } from './memory-tree-renderer.js';
+export * from './constants.js';
+export type { TreeNode } from './memory-tree-renderer.js';
 export declare class IndexDao {
     storeRoot: string;
     backupRoot: string;
     indexCache: IndexData | null;
-    private mutex;
+    private store;
+    private reconciler;
+    private catalog;
+    private renderer;
     constructor(storeRoot: string, options?: {
         backupRoot?: string;
     });
     get indexPath(): string;
     loadIndex(): IndexData;
     saveIndex(index: IndexData): void;
-    private runExclusive;
     getIndex(): IndexData;
     getBackupId(): string;
     backupIndex(backupId: string): {
@@ -72,5 +52,6 @@ export declare class IndexDao {
         title: string;
         tags: string[];
     }[];
+    buildMemoryTreeData(): TreeNode;
     buildMemoryIndexTree(recentLimit?: number): string;
 }