@zooique/memora 0.1.0

package/dist/memory/projectManager.js

@@ -0,0 +1,441 @@
+/**
+ * 项目管理器 — M-207 多项目并发
+ *
+ * 核心职责：
+ *   - 管理项目注册表（~/.memora/projects.json）
+ *   - 锁文件机制（.memora/.lock）防止同项目并发写入导致数据损坏
+ *   - Agent 级资源管理（memora.db 全局共享，不随项目切换重建）
+ *   - 两层记忆加载：项目级（projectPath/.memora/）→ Agent 级（configDir）
+ *   - 项目切换（只更新 projectPath + security + 重新加载项目 rules/skills）
+ *
+ * 设计原则（单 Agent 模型）：
+ *   - memora.db 只有一个（Agent 级），所有项目共享同一记忆数据库
+ *   - 项目切换不重建数据库，只更新安全守卫 + 重新扫描项目规则
+ *   - 项目级 .memora/ 仅存放 rules/ 和 skills/（无 memora.db）
+ *
+ * 锁文件策略：
+ *   - 打开项目时创建 .lock 文件（含 PID + 时间戳 + 主机名）
+ *   - 关闭/切换项目时删除 .lock 文件
+ *   - 检测到残留锁时：判断进程是否存活 → 存活则警告 / 已死则清理
+ *   - 不强制阻止并发（CLI-first，用户决定）
+ *
+ * 详见 ADR-008 · 目录结构按"职责分层"
+ */
+import { resolve, join } from 'node:path';
+import { hostname } from 'node:os';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { mkdir, readFile, writeFile, unlink } from 'node:fs/promises';
+import { FileStore } from '../memory/store.js';
+import { InMemoryStorage } from '../memory/inMemoryStorage.js';
+import { MemoryLoader } from '../memory/loader.js';
+import { logger } from '../logging/logger.js';
+import { toError } from '../utils/errors.js';
+import { expandHome } from '../utils/path.js';
+import { SOURCE_LABELS } from '../memory/types.js';
+// ─── QC-24 类型守卫 ─────────────────────────────────────
+// 对不可信磁盘文件 JSON.parse 结果进行运行时校验，替代 `as` 类型断言
+/**
+ * 判断值是否为非数组对象（排除 null）
+ *
+ * @param value 待校验的值
+ * @returns true 表示是普通对象
+ */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 判断值是否为 LockInfo（锁文件结构）
+ *
+ * @param value 待校验的值
+ * @returns true 表示符合 LockInfo 结构
+ */
+function isLockInfo(value) {
+    if (!isPlainObject(value))
+        return false;
+    return (typeof value['pid'] === 'number' &&
+        typeof value['acquiredAt'] === 'string' &&
+        typeof value['hostname'] === 'string');
+}
+/**
+ * 判断值是否为 ProjectEntry（项目注册表条目）
+ *
+ * @param value 待校验的值
+ * @returns true 表示符合 ProjectEntry 结构
+ */
+function isProjectEntry(value) {
+    if (!isPlainObject(value))
+        return false;
+    return (typeof value['path'] === 'string' &&
+        typeof value['name'] === 'string' &&
+        typeof value['lastOpened'] === 'string');
+}
+/**
+ * 判断值是否为 ProjectEntry 数组
+ *
+ * 过滤掉不符合结构的条目，仅保留合法条目
+ *
+ * @param value 待校验的值
+ * @returns 解析后的合法条目数组（损坏时返回空数组）
+ */
+function asProjectEntryArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter(isProjectEntry);
+}
+/**
+ * 项目管理器
+ *
+ * 管理多项目的生命周期：
+ * 1. 初始化当前项目（加锁 + 加载两层配置）
+ * 2. /project <name> 切换到新项目（解锁旧项目 + 加锁新项目）
+ * 3. 退出时清理锁文件
+ */
+export class ProjectManager {
+    /** 项目注册表路径 */
+    registryPath;
+    /** Agent 级数据目录（memora.db 所在目录） */
+    agentDataDir;
+    /** Agent 级存储实例（全局共享，不随项目切换重建） */
+    agentIndex = null;
+    /** 当前打开的项目路径 */
+    currentProjectPath = null;
+    /** 当前持有的锁文件路径 */
+    currentLockPath = null;
+    /** 外部注入的存储实例（可选，不传则内部创建 InMemoryStorage 兜底） */
+    externalStorage;
+    /** A-004: SecurityGuard 工厂函数（由 Agent 层注入） */
+    createSecurityGuard;
+    constructor(options) {
+        const { dataDir, storage, registryDir, createSecurityGuard } = options;
+        const memoraHome = resolve(expandHome(dataDir));
+        this.agentDataDir = memoraHome;
+        // 注册表目录：优先使用宿主指定的用户级路径，避免每项目重复存储
+        const registryHome = registryDir ? resolve(expandHome(registryDir)) : memoraHome;
+        this.registryPath = join(registryHome, 'projects.json');
+        // 保存外部注入的存储实例（宿主项目注入时使用）
+        this.externalStorage = storage ?? null;
+        // A-004: 保存 SecurityGuard 工厂函数
+        this.createSecurityGuard = createSecurityGuard;
+    }
+    /**
+     * 确保 Agent 级资源已初始化（存储实例）
+     * 存储实例在整个 Agent 生命周期内共享，不随项目切换重建
+     *
+     * 如果构造时注入了外部存储实例，直接使用；
+     * 否则内部创建 InMemoryStorage（非持久化兜底，仅开发/测试用）。
+     */
+    async ensureAgentResources() {
+        if (!this.agentIndex) {
+            await mkdir(this.agentDataDir, { recursive: true });
+            // 优先使用外部注入的存储实例
+            if (this.externalStorage) {
+                this.agentIndex = this.externalStorage;
+            }
+            else {
+                // 兜底：InMemoryStorage（非持久化，不依赖 native 模块）
+                // 生产环境应由宿主注入持久化实现（如 SqliteStorage）
+                logger.warn({ hasStorage: false }, '未注入持久化存储实现，Agent 将使用 InMemoryStorage（数据重启后丢失）');
+                this.agentIndex = new InMemoryStorage();
+            }
+        }
+        return { index: this.agentIndex };
+    }
+    /**
+     * 初始化指定项目
+     *
+     * 两层记忆加载：
+     *   1) 项目级：扫描 projectPath/.memora/rules/ + skills/
+     *   2) Agent 级：扫描 configDir 下的所有配置（rules/skills/personas/tools）
+     *
+     * 全局规则不再由内核硬编码路径，宿主可通过 configDir 统一管理。
+     *
+     * memora.db 是 Agent 级共享资源，不随项目切换重建。
+     *
+     * @param projectPath 项目根目录
+     * @param projectName 项目名称（可选，默认取目录名）
+     * @param configDir Agent 级配置目录（personas/rules/skills/tools）
+     */
+    async initProject(projectPath, projectName, configDir) {
+        // 如果已有打开的项目，先关闭（释放旧项目锁，但不关 Agent 级 DB）
+        if (this.currentProjectPath) {
+            await this.closeProject();
+        }
+        const memoraDir = this.resolveMemoraDir(projectPath);
+        // 获取锁文件（项目级锁，防止同项目并发）
+        await this.acquireLock(memoraDir);
+        this.currentProjectPath = projectPath;
+        this.currentLockPath = join(memoraDir, '.lock');
+        // FD-24: 后续步骤失败时释放锁并重置状态，避免锁文件残留导致下次启动检测失败
+        try {
+            // 确保项目 .memora/ 目录存在
+            await mkdir(memoraDir, { recursive: true });
+            // Agent 级共享资源（memora.db 只有一个）
+            const { index } = await this.ensureAgentResources();
+            // 合并加载结果（两层扫描汇总）
+            const loadResult = { loaded: 0, skipped: 0, errors: [] };
+            // 1) 项目级 FileStore：扫描 projectPath/.memora/ 下的 rules/ + skills/
+            const projectFileStore = new FileStore(memoraDir);
+            const projectLoader = new MemoryLoader(projectFileStore, index);
+            const projectResult = await projectLoader.loadAllToIndex();
+            loadResult.loaded += projectResult.loaded;
+            loadResult.skipped += projectResult.skipped;
+            loadResult.errors.push(...projectResult.errors);
+            // 2) Agent 级 FileStore：扫描 configDir 下的所有配置（rules/skills/personas/tools）
+            if (configDir) {
+                const configFileStore = new FileStore(configDir);
+                const configLoader = new MemoryLoader(configFileStore, index);
+                const configResult = await configLoader.loadAllToIndex();
+                loadResult.loaded += configResult.loaded;
+                loadResult.skipped += configResult.skipped;
+                loadResult.errors.push(...configResult.errors);
+            }
+            // bootstrap 过滤：按 source 获取 rule + skill 必召记忆（跳过 persona，由 PersonaManager 管理）
+            const rules = index.getBySource(SOURCE_LABELS.RULE);
+            const skills = index.getBySource(SOURCE_LABELS.SKILL);
+            const bootstrapMemories = [...rules, ...skills];
+            // A-004: 安全守卫由 Agent 层注入的工厂函数创建，解除 memory→security 反向依赖
+            const security = this.createSecurityGuard
+                ? this.createSecurityGuard(projectPath, memoraDir, configDir, this.agentDataDir)
+                : null;
+            // 注册到项目表
+            const name = projectName || this.inferProjectName(projectPath);
+            this.registerProject(projectPath, name);
+            logger.info({
+                projectPath,
+                projectName: name,
+                memoraDir,
+                loaded: loadResult.loaded,
+                bootstrapCount: bootstrapMemories.length,
+            }, '项目初始化完成');
+            return {
+                projectPath,
+                projectName: name,
+                memoraDir,
+                dbPath: join(this.agentDataDir, 'memora.db'),
+                fileStore: projectFileStore,
+                index,
+                security,
+                bootstrapMemories,
+                loadResult,
+            };
+        }
+        catch (err) {
+            // FD-24: 后续步骤失败时释放锁并重置状态，避免锁文件残留导致下次启动检测失败
+            await this.releaseLock().catch((releaseErr) => {
+                logger.warn({ err: releaseErr }, '释放项目锁失败');
+            });
+            this.currentProjectPath = null;
+            this.currentLockPath = null;
+            throw err;
+        }
+    }
+    /**
+     * 关闭当前项目
+     * 释放锁文件，但不关闭 Agent 级数据库（memora.db 是共享的）
+     */
+    async closeProject() {
+        // Agent 级 index/sessionStore 不关闭——它们是共享的，在整个 Agent 生命周期内持久存在
+        await this.releaseLock();
+        this.currentProjectPath = null;
+        this.currentLockPath = null;
+    }
+    /**
+     * 完全关闭：释放项目锁 + 关闭 Agent 级数据库
+     * 应在 Agent 整体关闭时调用（而非项目切换时）
+     */
+    async shutdown() {
+        if (this.currentProjectPath) {
+            await this.closeProject();
+        }
+        if (this.agentIndex) {
+            try {
+                this.agentIndex.close?.();
+            }
+            catch (err) {
+                logger.warn({ err }, '关闭 Agent 数据库失败');
+            }
+            this.agentIndex = null;
+        }
+    }
+    /**
+     * 列出已注册的项目（IX-02：统一为 getter 风格，与 persona/skill 一致）
+     */
+    get list() {
+        return this.readRegistry();
+    }
+    /**
+     * 列出已注册的项目
+     * @deprecated 请使用 `projectManager.list` getter 代替
+     */
+    listProjects() {
+        return this.readRegistry();
+    }
+    /**
+     * 注册项目到注册表
+     */
+    registerProject(projectPath, name) {
+        const registry = this.readRegistry();
+        // Windows 文件系统不区分大小写，路径大小写不同视为同一项目
+        const existing = registry.findIndex((e) => e.path.toLowerCase() === projectPath.toLowerCase());
+        const entry = {
+            path: projectPath,
+            name,
+            lastOpened: new Date().toISOString(),
+        };
+        if (existing >= 0) {
+            registry[existing] = entry;
+        }
+        else {
+            registry.push(entry);
+        }
+        this.writeRegistry(registry);
+    }
+    /**
+     * 从注册表移除项目
+     */
+    unregisterProject(projectPath) {
+        const registry = this.readRegistry();
+        // Windows 文件系统不区分大小写，大小写不同视为同一项目
+        const filtered = registry.filter((e) => e.path.toLowerCase() !== projectPath.toLowerCase());
+        this.writeRegistry(filtered);
+    }
+    /**
+     * 获取当前项目路径
+     */
+    get currentProject() {
+        return this.currentProjectPath;
+    }
+    /**
+     * 获取锁文件
+     * 如果锁文件存在且进程存活，发出警告但不阻止
+     * 如果锁文件存在但进程已死，清理残留锁
+     */
+    async acquireLock(memoraDir) {
+        const lockPath = join(memoraDir, '.lock');
+        try {
+            // 尝试读取锁文件（存在时）
+            const raw = await readFile(lockPath, 'utf-8');
+            // QC-24 使用类型守卫校验 JSON.parse 结果，替代 `as LockInfo` 类型断言
+            const parsed = JSON.parse(raw);
+            if (!isLockInfo(parsed)) {
+                // 锁文件结构损坏，清理后重新获取
+                logger.warn({ path: lockPath }, '锁文件结构损坏，清理残留');
+                await this.safeUnlink(lockPath);
+                return;
+            }
+            const info = parsed;
+            // 检查进程是否存活
+            if (this.isProcessAlive(info.pid)) {
+                logger.warn({ pid: info.pid, acquiredAt: info.acquiredAt, hostname: info.hostname }, '项目已被其他进程打开（锁文件存在），继续操作可能导致数据冲突');
+            }
+            else {
+                // 残留锁，清理
+                logger.info({ pid: info.pid }, '清理残留锁文件（进程已退出）');
+                await this.safeUnlink(lockPath);
+            }
+        }
+        catch (err) {
+            // 锁文件不存在或损坏，清理：记录 debug 日志便于排查（不存在属正常首次启动）
+            logger.debug({ path: lockPath, err: toError(err).message }, '锁文件读取失败，清理残留');
+            await this.safeUnlink(lockPath);
+        }
+        // 写入新锁
+        const lockInfo = {
+            pid: process.pid,
+            acquiredAt: new Date().toISOString(),
+            hostname: hostname(),
+        };
+        await mkdir(memoraDir, { recursive: true });
+        await writeFile(lockPath, JSON.stringify(lockInfo, null, 2), 'utf-8');
+    }
+    /**
+     * 释放锁文件
+     */
+    async releaseLock() {
+        if (this.currentLockPath) {
+            await this.safeUnlink(this.currentLockPath);
+        }
+    }
+    /**
+     * 安全删除文件（忽略不存在的错误）
+     */
+    async safeUnlink(filePath) {
+        try {
+            await unlink(filePath);
+        }
+        catch (err) {
+            logger.debug({ path: filePath, err: toError(err).message }, 'safeUnlink 忽略删除失败');
+        }
+    }
+    /**
+     * 检查进程是否存活
+     * Windows: tasklist /FI "PID eq <pid>"
+     * POSIX: kill(pid, 0)
+     */
+    isProcessAlive(pid) {
+        try {
+            // 发送信号 0 检查进程是否存在（POSIX 兼容）
+            // Windows 上 process.kill(pid, 0) 也会抛出错误如果进程不存在
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            logger.debug({ pid }, '进程不存在');
+            return false;
+        }
+    }
+    /**
+     * 解析项目的 .memora/ 目录路径
+     * 每个项目有独立的 .memora/ 目录（在项目根目录下）
+     * 这与 config.memory.dataDir（用户级默认目录）不同
+     */
+    resolveMemoraDir(projectPath) {
+        return resolve(projectPath, '.memora');
+    }
+    /**
+     * 从项目路径推断项目名称
+     * 取路径最后一段目录名
+     */
+    inferProjectName(projectPath) {
+        const parts = projectPath.replace(/[/\\]+$/, '').split(/[/\\]/);
+        return parts[parts.length - 1] || 'unnamed';
+    }
+    /**
+     * 读取项目注册表
+     *
+     * 同步读取：list getter 契约要求同步返回，注册表操作低频，同步 I/O 影响可控
+     * 损坏时返回空数组并记录警告日志，避免静默吞错掩盖磁盘故障
+     */
+    readRegistry() {
+        if (!existsSync(this.registryPath)) {
+            return [];
+        }
+        try {
+            const raw = readFileSync(this.registryPath, 'utf-8');
+            // QC-24 使用类型守卫校验 JSON.parse 结果，替代 `as ProjectEntry[]` 类型断言
+            // 过滤掉不符合结构的条目，仅保留合法条目
+            const parsed = JSON.parse(raw);
+            const entries = asProjectEntryArray(parsed);
+            if (entries.length === 0 && Array.isArray(parsed) && parsed.length > 0) {
+                // 数组存在但所有条目都不合法，记录警告
+                logger.warn({ path: this.registryPath, totalEntries: parsed.length }, '项目注册表所有条目结构不合法，返回空列表');
+            }
+            return entries;
+        }
+        catch (err) {
+            // 注册表损坏：记录警告日志便于排查（不存在属正常首次启动，损坏需排查）
+            logger.warn({ path: this.registryPath, err: toError(err).message }, '项目注册表解析失败，返回空列表');
+            return [];
+        }
+    }
+    /**
+     * 写入项目注册表
+     */
+    writeRegistry(entries) {
+        // 确保目录存在
+        const dir = this.registryPath.replace(/[/\\][^/\\]+$/, '');
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(this.registryPath, JSON.stringify(entries, null, 2), 'utf-8');
+    }
+}
+//# sourceMappingURL=projectManager.js.map

package/dist/memory/projectManager.js.map

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

package/dist/memory/recall.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 记忆召回 — 简化关键词搜索
+ *
+ * 设计哲学：每次用户发消息，从所有记忆中搜索最相关的几条注入上下文
+ * 基于基元驱动模型，通过 source 开放字符串区分记忆来源，
+ * 通过双通道（语义 + 关键词）召回，无需独立管理器
+ *
+ * 详见 ADR-004 · 记忆统一模型 + architecture_philosophy_rules.md §6 增量召回
+ */
+import type { Memory } from '../memory/types.js';
+import type { IMemoryStorage } from '../memory/storageInterface.js';
+import type { VectorStore } from '../memory/vectorStore.js';
+/** 语义搜索召回倍率（在最终 limit 基础上多召回一些，供后续融合排序） */
+export declare const RECALL_LIMIT_MULTIPLIER = 2;
+/** 综合排序时语义相似度权重 */
+export declare const VECTOR_SCORE_WEIGHT = 0.6;
+/** 综合排序时记忆 score 权重 */
+export declare const MEMORY_SCORE_WEIGHT = 0.4;
+/** 一天对应的毫秒数 */
+export declare const ONE_DAY_MS: number;
+/**
+ * 从文本中提取关键词（用于记忆召回）
+ *
+ * 基于 segmentText() 精确分词，叠加停用词过滤 + 英文词补充 + 去重。
+ * 分词基础设施统一由 segmenter.ts 提供，避免重复实现。
+ *
+ * @param input - 输入文本
+ * @returns 关键词数组（去重 + 停用词过滤）
+ */
+export declare function extractKeywords(input: string): string[];
+/**
+ * 召回选项
+ */
+export interface RecallOptions {
+    /** 返回数量上限（默认 5） */
+    limit?: number;
+    /** 排除的 source 标签（默认排除 persona 和 rule） */
+    excludeSources?: string[];
+    /** 向量存储（可选，提供时启用语义搜索） */
+    vectorStore?: VectorStore;
+    /** 语义搜索相似度阈值（默认 0.3） */
+    minSimilarity?: number;
+}
+/**
+ * 从记忆存储中搜索相关记忆
+ *
+ * 双通道召回策略：
+ * 1. 语义搜索（VectorStore 可用时）：向量余弦相似度
+ * 2. 关键词搜索（兜底）：LIKE 匹配
+ * 3. 两路结果合并去重，按 score + similarity 综合排序
+ * 4. 排除已单独注入的记忆（persona、rule）
+ * 5. 返回 top N
+ *
+ * @param storage - 记忆存储实例
+ * @param query - 搜索查询文本
+ * @param options - 召回选项
+ * @returns 匹配的记忆列表
+ */
+export declare function recall(storage: IMemoryStorage, query: string, options?: RecallOptions): Promise<Memory[]>;
+/**
+ * 召回时提升记忆的 score（上限 1.0）
+ *
+ * 每次被召回时，记忆的 score 略微提升，体现"越常用越重要"。
+ *
+ * @param memory - 被召回的记忆
+ * @param now - 当前时间戳（ISO 8601）
+ */
+export declare function boostScore(memory: Memory, now?: string): void;
+/**
+ * 对单条记忆执行衰减计算
+ *
+ * @param memory - 要衰减的记忆
+ * @param now - 当前时间（Date 对象）
+ * @returns 是否实际发生了衰减
+ */
+export declare function applyDecayToMemory(memory: Memory, now: Date): boolean;
+//# sourceMappingURL=recall.d.ts.map

package/dist/memory/recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall.d.ts","sourceRoot":"","sources":["../../src/memory/recall.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAU3D,2CAA2C;AAC3C,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,mBAAmB;AACnB,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,uBAAuB;AACvB,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAiBvC,eAAe;AACf,eAAO,MAAM,UAAU,QAAsB,CAAC;AAE9C;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAUvD;AAID;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,yBAAyB;IACzB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,wBAAwB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,MAAM,CAC1B,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,MAAM,EAAE,CAAC,CAoEnB;AAID;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAG7D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAcrE"}