@customize-agent/knowledge 1.0.1

package/dist/core/knowledge-base-manager.js

@@ -0,0 +1,300 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { TextChunker } from '../chunking/text-chunker.js';
+import { FileClassifier } from '../classification/classifier.js';
+import { ALL_CATEGORIES, DEFAULT_CATEGORY_DIRS, GLOBAL_KNOWLEDGE_DIR, USER_DATA_DIR } from '../constants.js';
+import { DedupEngine } from '../dedup/dedup-engine.js';
+import { RelationshipDetector } from '../dedup/relationship-detector.js';
+import { HashEmbeddingProvider } from '../embedding/embedding-provider.js';
+import { ContentExtractor } from '../extraction/content-extractor.js';
+import { FederationSearch } from '../search/federation-search.js';
+import { CollectionManager } from '../vector/collection-manager.js';
+import { VectorIndexer } from '../vector/vector-indexer.js';
+import { ChangeTracker } from './change-tracker.js';
+import { KnowledgeFileScanner } from './file-scanner.js';
+import { IndexStateStore } from './index-state-store.js';
+import { getProjectKbPath, ProjectConfigManager } from './project-config.js';
+export class KnowledgeBaseManager {
+    scope;
+    projectRoot;
+    projectId;
+    kbPath;
+    store;
+    classifier = new FileClassifier();
+    scanner = new KnowledgeFileScanner();
+    collections = new CollectionManager();
+    extractor;
+    chunker = new TextChunker();
+    dedup = new DedupEngine();
+    relationshipDetector = new RelationshipDetector();
+    embeddingProvider;
+    vectorStores;
+    configManager = new ProjectConfigManager();
+    projectConfig;
+    lastSkippedFiles = [];
+    constructor(options) {
+        this.scope = options.scope;
+        this.projectRoot = options.projectRoot;
+        this.projectId = options.projectId;
+        this.embeddingProvider = options.embeddingProvider ?? new HashEmbeddingProvider();
+        this.vectorStores = options.vectorStores ?? new Map();
+        this.extractor = new ContentExtractor(options.externalExtractors);
+        const storageRoot = options.storageRoot ?? path.join(os.homedir(), USER_DATA_DIR);
+        if (this.scope === 'global') {
+            this.kbPath = options.kbPath ?? path.join(storageRoot, GLOBAL_KNOWLEDGE_DIR);
+            this.store = new IndexStateStore(path.join(storageRoot, 'global-knowledge.db'));
+        }
+        else {
+            if (!options.projectRoot || !options.projectId) {
+                throw new Error('project knowledge base requires projectRoot and projectId');
+            }
+            this.kbPath = options.kbPath ?? getProjectKbPath(options.projectRoot);
+            this.store = new IndexStateStore(path.join(storageRoot, 'projects', options.projectId, 'kb.db'));
+        }
+    }
+    initialize() {
+        if (this.scope === 'project' && this.projectRoot) {
+            this.projectConfig = this.configManager.loadOrCreate(this.projectRoot);
+            fs.mkdirSync(this.kbPath, { recursive: true });
+            const dirs = this.projectConfig.categoryDirs;
+            for (const category of ALL_CATEGORIES) {
+                fs.mkdirSync(path.join(this.kbPath, dirs[category] ?? DEFAULT_CATEGORY_DIRS[category]), { recursive: true });
+            }
+        }
+        if (this.scope === 'global') {
+            fs.mkdirSync(this.kbPath, { recursive: true });
+        }
+    }
+    async incrementalIndex() {
+        this.initialize();
+        const kbIgnore = this.scanner.loadKbIgnore(this.kbPath);
+        const configIgnore = this.projectConfig?.kbignore ?? [];
+        const diskFiles = await this.scanner.scan(this.kbPath, [...kbIgnore, ...configIgnore]);
+        const tracker = new ChangeTracker(this.store);
+        const diff = await tracker.computeDiff(diskFiles, this.classifier, this.kbPath);
+        for (const deleted of diff.deletedFiles) {
+            this.store.deleteRecord(deleted.relativePath);
+        }
+        const now = Date.now();
+        const indexedBefore = [...this.store.loadActiveRecords().values()];
+        for (const file of [...diff.newFiles, ...diff.modifiedFiles]) {
+            const hash = tracker.hashFile(file.absolutePath);
+            const duplicate = this.store.findExactDuplicate(hash, file.relativePath);
+            const extraction = await this.extractor.extract(file);
+            if (!this.hasUsableContent(extraction.text, extraction.metadata)) {
+                diff.skippedFiles.push({ file, reason: extraction.warnings[0] ?? '未解析出可用于模型的正文内容，已跳过向量化' });
+                this.store.deleteRecord(file.relativePath);
+                continue;
+            }
+            const normalizedHash = this.dedup.normalizedHash(extraction.text);
+            const normalizedDuplicate = !duplicate && normalizedHash
+                ? this.store.findNormalizedDuplicate(normalizedHash, file.relativePath)
+                : undefined;
+            const chunks = duplicate ? [] : this.chunker.chunk(extraction.text, file, extraction.metadata);
+            const collectionName = this.scope === 'global'
+                ? this.collections.getCollectionName('global', file.category)
+                : this.collections.getCollectionName('project', file.category, this.projectId);
+            this.store.upsertFileHash({
+                contentHash: hash,
+                filePath: file.relativePath,
+                fileSize: file.fileSize,
+                category: file.category,
+                normalizedHash,
+            });
+            if (duplicate) {
+                this.store.addRelationship({
+                    sourceFile: file.relativePath,
+                    targetFile: duplicate.filePath,
+                    relationshipType: 'exact_duplicate',
+                    confidence: 1,
+                    detail: `SHA-256 完全相同: ${hash}`,
+                    userConfirmed: 0,
+                });
+            }
+            else if (normalizedDuplicate && normalizedHash) {
+                this.store.addRelationship({
+                    sourceFile: file.relativePath,
+                    targetFile: normalizedDuplicate.filePath,
+                    relationshipType: this.dedup.relationshipForFormats(file.format, normalizedDuplicate.category),
+                    confidence: 0.95,
+                    detail: `归一化内容哈希相同: ${normalizedHash}`,
+                    userConfirmed: 0,
+                });
+            }
+            if (!duplicate && extraction.text.length > 1000) {
+                const minHash = this.dedup.computeMinHash(extraction.text);
+                if (minHash) {
+                    for (const existing of this.store.listMinHashes(file.relativePath)) {
+                        const similarity = this.dedup.estimateSimilarity(minHash.signature, existing.signature);
+                        const relationshipType = this.dedup.relationshipForSimilarity(similarity);
+                        if (relationshipType) {
+                            this.store.addRelationship({
+                                sourceFile: file.relativePath,
+                                targetFile: existing.filePath,
+                                relationshipType,
+                                confidence: similarity,
+                                detail: `MinHash 相似度: ${similarity.toFixed(3)}`,
+                                userConfirmed: 0,
+                            });
+                        }
+                    }
+                    this.store.upsertMinHash({
+                        filePath: file.relativePath,
+                        signature: minHash.signature,
+                        shingleCount: minHash.shingleCount,
+                    });
+                }
+            }
+            for (const relationship of this.relationshipDetector.detect(file, indexedBefore)) {
+                this.store.addRelationship(relationship);
+            }
+            this.store.upsertRecord({
+                relativePath: file.relativePath,
+                category: file.category,
+                format: file.format,
+                contentHash: hash,
+                fileSize: file.fileSize,
+                mtime: file.mtime,
+                chunkCount: chunks.length,
+                collectionName,
+                indexedAt: now,
+                lastVerifiedAt: now,
+                status: 'active',
+                metadataJson: JSON.stringify({
+                    mimeType: file.mimeType,
+                    extraction: extraction.metadata,
+                    warnings: extraction.warnings,
+                    extractionTimeMs: extraction.extractionTimeMs,
+                }),
+            });
+            this.store.replaceChunks(file.relativePath, chunks, {
+                category: file.category,
+                format: file.format,
+                collectionName,
+            });
+        }
+        const stats = this.getStats();
+        this.store.setMetadata('last_incremental_index_at', String(now));
+        this.store.setMetadata('total_chunks', String(stats.chunkCount));
+        this.store.setMetadata('total_files_indexed', String(stats.fileCount));
+        this.lastSkippedFiles = diff.skippedFiles;
+        return diff;
+    }
+    search(query, limit = 10) {
+        return this.store.searchChunks(query, limit);
+    }
+    async semanticSearch(query, options = {}) {
+        const queryEmbedding = await this.embeddingProvider.embedQuery(query);
+        const search = new FederationSearch(this.vectorStores);
+        return search.search({
+            query,
+            queryEmbedding,
+            topK: options.limit ?? 10,
+            scope: this.scope,
+            projectId: this.projectId,
+            collections: options.collections,
+            filters: options.filters,
+        });
+    }
+    listRelationships(filePath) {
+        return this.store.listRelationships(filePath);
+    }
+    listFiles() {
+        return this.store.listRecords();
+    }
+    async addFile(sourcePath, targetRelativePath) {
+        this.initialize();
+        const resolvedSource = path.resolve(sourcePath);
+        const relativePath = targetRelativePath ?? path.basename(resolvedSource);
+        const targetPath = this.resolveKbRelativePath(relativePath);
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+        fs.copyFileSync(resolvedSource, targetPath);
+        return this.incrementalIndex();
+    }
+    async uploadFile(fileName, content, targetRelativePath) {
+        this.initialize();
+        const relativePath = targetRelativePath ?? this.defaultUploadRelativePath(fileName);
+        const targetPath = this.resolveKbRelativePath(relativePath);
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+        fs.writeFileSync(targetPath, content);
+        return this.incrementalIndex();
+    }
+    listFailedFiles() {
+        return this.lastSkippedFiles;
+    }
+    async removeFile(relativePath) {
+        const targetPath = this.resolveKbRelativePath(relativePath);
+        if (fs.existsSync(targetPath))
+            fs.unlinkSync(targetPath);
+        this.store.deleteRecord(this.normalizeRelativePath(relativePath));
+    }
+    tagFile(relativePath, tags) {
+        this.store.setTags(this.normalizeRelativePath(relativePath), tags);
+    }
+    listTags(relativePath) {
+        return this.store.listTags(relativePath ? this.normalizeRelativePath(relativePath) : undefined);
+    }
+    addIgnoreRule(pattern) {
+        this.store.addIgnoreRule(pattern);
+        if (this.scope === 'project' && this.projectRoot) {
+            const config = this.projectConfig ?? this.configManager.loadOrCreate(this.projectRoot);
+            if (!config.kbignore.includes(pattern)) {
+                this.configManager.save(this.projectRoot, { ...config, kbignore: [...config.kbignore, pattern] });
+            }
+        }
+    }
+    listIgnoreRules() {
+        return this.store.listIgnoreRules();
+    }
+    async indexVectors(options = {}) {
+        const chunks = this.store.listChunks(options);
+        const indexer = new VectorIndexer(this.embeddingProvider, this.vectorStores);
+        const results = await indexer.indexChunks(chunks);
+        this.store.setMetadata('embedding_model', this.embeddingProvider.model);
+        this.store.setMetadata('embedding_dimension', String(this.embeddingProvider.dimensions));
+        this.store.setMetadata('last_vector_index_at', String(Date.now()));
+        return results;
+    }
+    getProjectConfig() {
+        return this.projectConfig;
+    }
+    getStats() {
+        const stats = this.store.getStats();
+        return {
+            scope: this.scope,
+            projectId: this.projectId,
+            fileCount: stats.fileCount,
+            chunkCount: stats.chunkCount,
+            totalSizeBytes: stats.totalSizeBytes,
+            lastIndexedAt: stats.lastIndexedAt,
+        };
+    }
+    close() {
+        this.store.close();
+    }
+    hasUsableContent(text, metadata) {
+        const coverage = String(metadata.contentCoverage ?? '');
+        if (coverage === 'metadata' || coverage === 'metadata_filename')
+            return false;
+        return text.trim().length > 0;
+    }
+    defaultUploadRelativePath(fileName) {
+        const classification = this.classifier.classifyVirtual(fileName);
+        const configDirs = this.projectConfig?.categoryDirs ?? DEFAULT_CATEGORY_DIRS;
+        const dir = configDirs[classification.category] ?? DEFAULT_CATEGORY_DIRS[classification.category];
+        return `${dir}/${path.basename(fileName)}`;
+    }
+    resolveKbRelativePath(relativePath) {
+        const normalized = this.normalizeRelativePath(relativePath);
+        const targetPath = path.resolve(this.kbPath, normalized);
+        const root = path.resolve(this.kbPath);
+        if (targetPath !== root && !targetPath.startsWith(`${root}${path.sep}`)) {
+            throw new Error('relativePath escapes knowledge base root');
+        }
+        return targetPath;
+    }
+    normalizeRelativePath(relativePath) {
+        return relativePath.split(path.sep).join('/').replace(/^\/+/, '');
+    }
+}

package/dist/core/multi-project-manager.d.ts

@@ -0,0 +1,30 @@
+import type { FederatedResult, SearchFilters, SearchScope } from '../search/federation-search.js';
+import { FederationSearch } from '../search/federation-search.js';
+import type { CrossProjectDuplicate, ProjectInfo } from '../types.js';
+import { KnowledgeBaseManager } from './knowledge-base-manager.js';
+export declare class MultiProjectManager {
+    private readonly storageRoot;
+    private readonly registry;
+    private readonly configManager;
+    private readonly projects;
+    private globalKB?;
+    constructor(storageRoot?: string);
+    getProject(projectRoot: string): Promise<KnowledgeBaseManager>;
+    getGlobalKB(): Promise<KnowledgeBaseManager>;
+    listProjects(): Promise<ProjectInfo[]>;
+    search(projectRoot: string, query: string, options?: {
+        limit?: number;
+        scope?: SearchScope;
+    }): Promise<ReturnType<FederationSearch['merge']>>;
+    semanticSearch(projectRoot: string, query: string, options?: {
+        limit?: number;
+        scope?: SearchScope;
+        filters?: SearchFilters;
+        collections?: string[];
+    }): Promise<FederatedResult>;
+    findCrossProjectDuplicates(): Promise<CrossProjectDuplicate[]>;
+    forgetProject(projectId: string): Promise<void>;
+    closeProject(projectId: string): Promise<void>;
+    shutdown(): Promise<void>;
+    private updateRegistry;
+}

package/dist/core/multi-project-manager.js

@@ -0,0 +1,163 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { USER_DATA_DIR } from '../constants.js';
+import { FederationSearch } from '../search/federation-search.js';
+import { KnowledgeBaseManager } from './knowledge-base-manager.js';
+import { computeProjectId } from './project-id.js';
+import { getProjectKbPath, ProjectConfigManager } from './project-config.js';
+import { ProjectRegistry } from './project-registry.js';
+export class MultiProjectManager {
+    storageRoot;
+    registry;
+    configManager = new ProjectConfigManager();
+    projects = new Map();
+    globalKB;
+    constructor(storageRoot = path.join(os.homedir(), USER_DATA_DIR)) {
+        this.storageRoot = storageRoot;
+        this.registry = new ProjectRegistry(path.join(storageRoot, 'projects', 'registry.db'));
+    }
+    async getProject(projectRoot) {
+        const resolvedRoot = path.resolve(projectRoot);
+        const projectId = computeProjectId(resolvedRoot);
+        const existing = this.projects.get(projectId);
+        if (existing)
+            return existing;
+        const config = this.configManager.loadOrCreate(resolvedRoot);
+        const manager = new KnowledgeBaseManager({
+            scope: 'project',
+            projectRoot: resolvedRoot,
+            projectId,
+            kbPath: getProjectKbPath(resolvedRoot),
+            storageRoot: this.storageRoot,
+        });
+        manager.initialize();
+        this.projects.set(projectId, manager);
+        this.updateRegistry(manager, resolvedRoot, config.projectName, config.lastOpenedAt);
+        return manager;
+    }
+    async getGlobalKB() {
+        if (this.globalKB)
+            return this.globalKB;
+        const manager = new KnowledgeBaseManager({ scope: 'global', storageRoot: this.storageRoot });
+        manager.initialize();
+        await manager.incrementalIndex();
+        this.globalKB = manager;
+        return manager;
+    }
+    async listProjects() {
+        return this.registry.list();
+    }
+    async search(projectRoot, query, options = {}) {
+        const limit = options.limit ?? 10;
+        const scope = options.scope ?? 'all';
+        const project = await this.getProject(projectRoot);
+        await project.incrementalIndex();
+        const items = [];
+        if (scope === 'project' || scope === 'all') {
+            items.push(...project.search(query, limit).map(result => ({
+                id: result.id,
+                content: result.content,
+                filePath: result.relativePath,
+                scope: 'project',
+                collection: result.collectionName,
+                score: result.score,
+            })));
+        }
+        if (scope === 'global' || scope === 'all') {
+            const global = await this.getGlobalKB();
+            items.push(...global.search(query, limit).map(result => ({
+                id: result.id,
+                content: result.content,
+                filePath: result.relativePath,
+                scope: 'global',
+                collection: result.collectionName,
+                score: result.score,
+            })));
+        }
+        return new FederationSearch().merge(items, limit, scope);
+    }
+    async semanticSearch(projectRoot, query, options = {}) {
+        const scope = options.scope ?? 'all';
+        const project = await this.getProject(projectRoot);
+        await project.incrementalIndex();
+        if (scope === 'project') {
+            return project.semanticSearch(query, options);
+        }
+        const projectResults = scope === 'all'
+            ? await project.semanticSearch(query, options)
+            : { results: [], scopesSearched: [], queryTimeMs: 0 };
+        if (scope === 'global') {
+            const global = await this.getGlobalKB();
+            return global.semanticSearch(query, options);
+        }
+        const global = await this.getGlobalKB();
+        const globalResults = await global.semanticSearch(query, options);
+        return new FederationSearch().merge([...projectResults.results, ...globalResults.results], options.limit ?? 10, 'all');
+    }
+    async findCrossProjectDuplicates() {
+        const projects = this.registry.list();
+        const byHash = new Map();
+        for (const project of projects) {
+            const manager = this.projects.get(project.projectId) ?? new KnowledgeBaseManager({
+                scope: 'project',
+                projectRoot: project.projectRoot,
+                projectId: project.projectId,
+                kbPath: project.kbPath,
+                storageRoot: this.storageRoot,
+            });
+            for (const item of manager.store.listContentHashes()) {
+                const duplicate = byHash.get(item.contentHash) ?? { contentHash: item.contentHash, files: [] };
+                duplicate.files.push({
+                    projectId: project.projectId,
+                    projectRoot: project.projectRoot,
+                    relativePath: item.relativePath,
+                });
+                byHash.set(item.contentHash, duplicate);
+            }
+            if (!this.projects.has(project.projectId))
+                manager.close();
+        }
+        return [...byHash.values()].filter(item => item.files.length > 1);
+    }
+    async forgetProject(projectId) {
+        const manager = this.projects.get(projectId);
+        if (manager) {
+            manager.close();
+            this.projects.delete(projectId);
+        }
+        this.registry.forget(projectId);
+    }
+    async closeProject(projectId) {
+        const manager = this.projects.get(projectId);
+        if (!manager)
+            return;
+        manager.close();
+        this.projects.delete(projectId);
+    }
+    async shutdown() {
+        for (const manager of this.projects.values()) {
+            manager.close();
+        }
+        this.projects.clear();
+        this.globalKB?.close();
+        this.globalKB = undefined;
+        this.registry.close();
+    }
+    updateRegistry(manager, projectRoot, projectName, lastOpenedAt) {
+        const stats = manager.getStats();
+        if (!manager.projectId)
+            throw new Error('project manager missing projectId');
+        this.registry.upsert({
+            projectId: manager.projectId,
+            projectRoot,
+            projectName,
+            kbPath: manager.kbPath,
+            fileCount: stats.fileCount,
+            chunkCount: stats.chunkCount,
+            totalSizeBytes: stats.totalSizeBytes,
+            lastIndexedAt: stats.lastIndexedAt,
+            lastOpenedAt,
+            status: 'active',
+        });
+    }
+}

package/dist/core/project-config.d.ts

@@ -0,0 +1,9 @@
+import type { ProjectConfig } from '../types.js';
+export declare function getProjectConfigPath(projectRoot: string): string;
+export declare function getProjectKbPath(projectRoot: string): string;
+export declare function ensureProjectCustomizeFile(projectRoot: string): void;
+export declare class ProjectConfigManager {
+    loadOrCreate(projectRoot: string): ProjectConfig;
+    save(projectRoot: string, config: ProjectConfig): void;
+    private withDefaults;
+}

package/dist/core/project-config.js

@@ -0,0 +1,73 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { DEFAULT_CATEGORY_DIRS, KNOWLEDGE_BASE_DIR, PROJECT_CONFIG_PATH, USER_DATA_DIR } from '../constants.js';
+import { computeProjectId } from './project-id.js';
+export function getProjectConfigPath(projectRoot) {
+    const projectId = computeProjectId(projectRoot);
+    return path.join(os.homedir(), USER_DATA_DIR, 'projects', projectId, ...PROJECT_CONFIG_PATH.slice(1));
+}
+export function getProjectKbPath(projectRoot) {
+    return path.join(projectRoot, KNOWLEDGE_BASE_DIR);
+}
+const DEFAULT_CUSTOMIZE_MD = `# Customize Agent 配置示例
+
+你可以在这个文件里描述本项目希望 Agent 遵守的角色、规则和工作方式。
+
+## Agent 角色
+你是本项目的工程助手，请优先理解现有代码结构，再进行修改。
+
+## 工作规则
+- 修改代码前先阅读相关文件。
+- 保持改动简单、直接、可验证。
+- 不要覆盖用户已有文件或未确认的业务逻辑。
+- 涉及知识库资料时，通过知识库检索使用解析后的内容，不直接读取 knowledgeBase 原始文件。
+
+## 项目偏好
+- 使用中文回复。
+- 重要改动完成后运行必要的类型检查或构建检查。
+`;
+export function ensureProjectCustomizeFile(projectRoot) {
+    const filePath = path.join(projectRoot, 'CUSTOMIZE.md');
+    if (!fs.existsSync(filePath)) {
+        fs.mkdirSync(projectRoot, { recursive: true });
+        fs.writeFileSync(filePath, DEFAULT_CUSTOMIZE_MD, 'utf8');
+    }
+}
+export class ProjectConfigManager {
+    loadOrCreate(projectRoot) {
+        ensureProjectCustomizeFile(projectRoot);
+        const configPath = getProjectConfigPath(projectRoot);
+        const now = Date.now();
+        if (fs.existsSync(configPath)) {
+            const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+            const config = this.withDefaults(projectRoot, raw, now);
+            this.save(projectRoot, { ...config, lastOpenedAt: now });
+            return { ...config, lastOpenedAt: now };
+        }
+        const config = this.withDefaults(projectRoot, {}, now);
+        this.save(projectRoot, config);
+        return config;
+    }
+    save(projectRoot, config) {
+        const configPath = getProjectConfigPath(projectRoot);
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+    }
+    withDefaults(projectRoot, raw, now) {
+        return {
+            projectId: raw.projectId ?? computeProjectId(projectRoot),
+            projectName: raw.projectName ?? path.basename(path.resolve(projectRoot)),
+            enabled: raw.enabled ?? true,
+            includeGlobal: raw.includeGlobal ?? true,
+            priorityOverGlobal: raw.priorityOverGlobal ?? true,
+            watch: raw.watch ?? true,
+            autoIndex: raw.autoIndex ?? true,
+            kbignore: raw.kbignore ?? [],
+            projectTags: raw.projectTags ?? [],
+            categoryDirs: { ...DEFAULT_CATEGORY_DIRS, ...(raw.categoryDirs ?? {}) },
+            createdAt: raw.createdAt ?? now,
+            lastOpenedAt: raw.lastOpenedAt ?? now,
+        };
+    }
+}

package/dist/core/project-id.d.ts

@@ -0,0 +1 @@
+export declare function computeProjectId(projectRoot: string): string;

package/dist/core/project-id.js

@@ -0,0 +1,8 @@
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+export function computeProjectId(projectRoot) {
+    return crypto.createHash('sha256')
+        .update(path.resolve(projectRoot))
+        .digest('hex')
+        .slice(0, 12);
+}

package/dist/core/project-registry.d.ts

@@ -0,0 +1,10 @@
+import type { ProjectInfo } from '../types.js';
+export declare class ProjectRegistry {
+    private readonly db;
+    constructor(dbPath: string);
+    upsert(project: ProjectInfo): void;
+    list(): ProjectInfo[];
+    forget(projectId: string): void;
+    close(): void;
+    private initTables;
+}

package/dist/core/project-registry.js

@@ -0,0 +1,70 @@
+import Database from 'better-sqlite3';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export class ProjectRegistry {
+    db;
+    constructor(dbPath) {
+        fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+        this.db = new Database(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.initTables();
+    }
+    upsert(project) {
+        this.db.prepare(`
+      INSERT INTO project_registry (
+        project_id, project_root, project_name, kb_path, file_count,
+        chunk_count, total_size_bytes, last_indexed_at, created_at,
+        last_opened_at, status
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(project_id) DO UPDATE SET
+        project_root = excluded.project_root,
+        project_name = excluded.project_name,
+        kb_path = excluded.kb_path,
+        file_count = excluded.file_count,
+        chunk_count = excluded.chunk_count,
+        total_size_bytes = excluded.total_size_bytes,
+        last_indexed_at = excluded.last_indexed_at,
+        last_opened_at = excluded.last_opened_at,
+        status = excluded.status
+    `).run(project.projectId, project.projectRoot, project.projectName ?? null, project.kbPath, project.fileCount, project.chunkCount, project.totalSizeBytes, project.lastIndexedAt, Date.now(), project.lastOpenedAt, project.status);
+    }
+    list() {
+        const rows = this.db.prepare('SELECT * FROM project_registry ORDER BY last_opened_at DESC').all();
+        return rows.map(row => ({
+            projectId: String(row.project_id),
+            projectRoot: String(row.project_root),
+            projectName: row.project_name == null ? undefined : String(row.project_name),
+            kbPath: String(row.kb_path),
+            fileCount: Number(row.file_count ?? 0),
+            chunkCount: Number(row.chunk_count ?? 0),
+            totalSizeBytes: Number(row.total_size_bytes ?? 0),
+            lastIndexedAt: Number(row.last_indexed_at ?? 0),
+            lastOpenedAt: Number(row.last_opened_at ?? 0),
+            status: String(row.status ?? 'idle'),
+        }));
+    }
+    forget(projectId) {
+        this.db.prepare('DELETE FROM project_registry WHERE project_id = ?').run(projectId);
+    }
+    close() {
+        this.db.close();
+    }
+    initTables() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS project_registry (
+        project_id      TEXT PRIMARY KEY,
+        project_root    TEXT NOT NULL UNIQUE,
+        project_name    TEXT,
+        kb_path         TEXT NOT NULL,
+        file_count      INTEGER NOT NULL DEFAULT 0,
+        chunk_count     INTEGER NOT NULL DEFAULT 0,
+        total_size_bytes INTEGER NOT NULL DEFAULT 0,
+        last_indexed_at INTEGER NOT NULL DEFAULT 0,
+        created_at      INTEGER NOT NULL,
+        last_opened_at  INTEGER NOT NULL,
+        status          TEXT NOT NULL DEFAULT 'active'
+      );
+      CREATE INDEX IF NOT EXISTS idx_registry_status ON project_registry(status);
+    `);
+    }
+}