@morningljn/mnemo 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ArtLjn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+<p align="center">
+  <img src="./banner.png" alt="mnemo" width="600">
+</p>
+
+<p align="center">
+  <a href="./README_zh.md">简体中文</a> | <strong>English</strong>
+</p>
+
+---
+
+## Why mnemo?
+
+AI coding assistants forget everything between sessions. `CLAUDE.md` stores static rules, but it can't search or reason over accumulated knowledge.
+
+mnemo gives your AI assistant a **searchable, structured memory layer** that persists across sessions:
+
+- **Search by meaning** — FTS5 full-text search + Jaccard reranking + bilingual expansion
+- **Trust scoring** — facts gain or lose trust over time based on feedback and decay
+- **Entity graph** — automatic entity extraction with multi-hop relationship queries
+- **Contradiction detection** — finds conflicting facts and demotes the older one
+- **Auto-dedup** — three-layer deduplication prevents duplicate facts
+
+## Quick Start
+
+```bash
+# Install
+npm install -g @artljn/mnemo
+
+# One-command setup (register MCP + write rules + set permissions)
+mnemo-init
+```
+
+That's it. Restart your AI assistant and it will have persistent memory.
+
+### Manual Setup
+
+If you prefer manual configuration:
+
+**1. Register MCP server:**
+
+```bash
+claude mcp add mnemo -- mnemo
+```
+
+**2. Add memory rules to `~/.claude/CLAUDE.md`:**
+
+```markdown
+# Memory System
+
+You have mnemo memory tools (fact_store / fact_feedback). Rules:
+
+## Rule 1: Search before answering
+After receiving a user message, call `fact_store(action="search", query="<keywords from user message>")`.
+Extract keywords from the user's actual message — do NOT use a fixed template.
+
+## Rule 2: Write on request
+When user says "remember", call `fact_store(action="add", content="...", category="...")`.
+Search first to avoid duplicates. Categories: identity / coding_style / tool_pref / workflow / general.
+
+## Rule 3: Feedback
+When a memory was useful, call `fact_feedback(action="helpful", fact_id=...)`.
+```
+
+**3. Allow tools in `~/.claude/settings.json`:**
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__mnemo__fact_store",
+      "mcp__mnemo__fact_feedback"
+    ]
+  }
+}
+```
+
+### Codex
+
+Add to your Codex MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "mnemo": {
+      "command": "mnemo"
+    }
+  }
+}
+```
+
+## Tools
+
+### `fact_store`
+
+The primary tool for reading and writing structured facts. Supports 9 actions:
+
+| Action | Description | Key Parameters |
+|--------|-------------|----------------|
+| `add` | Add a new fact (auto-deduplicates; merges if similar exists) | `content`, `category`, `tags` |
+| `search` | Keyword search with FTS5 + Jaccard reranking | `query`, `category`, `min_trust`, `limit` |
+| `probe` | Find all facts about a specific entity | `entity`, `min_trust`, `limit` |
+| `related` | Find facts related to an entity through shared context | `entity`, `min_trust`, `limit` |
+| `reason` | Multi-entity reasoning: find facts connected to all given entities | `entities`, `min_trust`, `limit` |
+| `contradict` | Detect pairs of facts that share entities but conflict in content | `limit` |
+| `update` | Update an existing fact's content, tags, category, or trust score | `fact_id`, `content`, `tags`, `category`, `trust_delta` |
+| `remove` | Delete a fact by ID | `fact_id` |
+| `list` | Browse facts sorted by trust score | `category`, `min_trust`, `limit` |
+
+### `fact_feedback`
+
+Rate a fact after use. Good facts rise, bad facts decay.
+
+| Action | Effect |
+|--------|--------|
+| `helpful` | +0.05 trust |
+| `unhelpful` | -0.10 trust |
+
+## Architecture
+
+```
+┌───────────────────┐   stdio    ┌────────────┐   SQLite    ┌─────────────────────┐
+│   MCP Client      │◄─────────►│  mnemo     │◄───────────►│ ~/.mnemo/facts.db   │
+│ (Claude / Codex)  │   JSON    │  server    │             │                     │
+└───────────────────┘           └─────┬──────┘             │ Tables:             │
+                                      │                    │   facts             │
+                               ┌──────┴──────┐             │   entities          │
+                               │             │             │   fact_entities     │
+                               │  Retriever  │  Security   │ Indexes:            │
+                               │  (search,   │  (PII scan, │   facts_fts (FTS5)  │
+                               │   probe,    │   injection │   idx_facts_trust   │
+                               │   reason)   │   detection)│   idx_facts_category│
+                               └─────────────┘             └─────────────────────┘
+```
+
+## Categories
+
+| Category | Description | Decay Rate |
+|----------|-------------|------------|
+| `identity` | User identity: name, role, preferences | 0.02/week |
+| `coding_style` | Coding conventions, naming, formatting | 0.03/week |
+| `tool_pref` | Tool and framework preferences | 0.03/week |
+| `workflow` | Development workflow, CI/CD, git practices | 0.02/week |
+| `general` | General knowledge and other facts | 0.03/week |
+
+## Development
+
+```bash
+npm install
+npm test        # run tests with vitest
+npm run build   # compile TypeScript
+npm start       # start MCP server
+```
+
+## License
+
+[MIT](./LICENSE)

package/README_zh.md

@@ -0,0 +1,156 @@
+<p align="center">
+  <img src="./banner.png" alt="mnemo" width="600">
+</p>
+
+<p align="center">
+  <strong>简体中文</strong> | <a href="./README.md">English</a>
+</p>
+
+---
+
+## 为什么需要 mnemo？
+
+AI 编程助手在会话结束后会忘记所有内容。`CLAUDE.md` 只能存储静态规则，无法搜索或推理积累的知识。
+
+mnemo 为你的 AI 助手提供**可搜索、结构化的记忆层**，跨会话持久化：
+
+- **语义搜索** — FTS5 全文检索 + Jaccard 重排序 + 中英双语扩展
+- **信任评分** — 事实随时间根据反馈和衰减获得或失去信任
+- **实体图谱** — 自动实体抽取，支持多跳关联查询
+- **矛盾检测** — 发现冲突事实并降级较旧的那条
+- **自动去重** — 三层去重机制（实体重叠、Jaccard 相似度、包含检测）
+
+## 快速开始
+
+```bash
+# 安装
+npm install -g @artljn/mnemo
+
+# 一键配置（注册 MCP + 写入规则 + 设置权限）
+mnemo-init
+```
+
+重启你的 AI 助手即可拥有持久记忆。
+
+### 手动配置
+
+如果你更喜欢手动配置：
+
+**1. 注册 MCP 服务器：**
+
+```bash
+claude mcp add mnemo -- mnemo
+```
+
+**2. 在 `~/.claude/CLAUDE.md` 中添加记忆规则：**
+
+```markdown
+# 记忆系统
+
+你有 mnemo 记忆工具（fact_store / fact_feedback）。规则：
+
+## 规则 1：回复前搜索
+收到用户消息后，调用 `fact_store(action="search", query="<用户消息的关键词>")`。
+必须从用户消息中动态提取关键词，不要用固定模板。
+
+## 规则 2：按需写入
+用户说"记住"时，调用 `fact_store(action="add", content="...", category="...")`。
+先搜索避免重复。类别：identity / coding_style / tool_pref / workflow / general。
+
+## 规则 3：反馈强化
+记忆有用时，调用 `fact_feedback(action="helpful", fact_id=...)`。
+```
+
+**3. 在 `~/.claude/settings.json` 中允许工具：**
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__mnemo__fact_store",
+      "mcp__mnemo__fact_feedback"
+    ]
+  }
+}
+```
+
+### Codex
+
+添加到你的 Codex MCP 配置：
+
+```json
+{
+  "mcpServers": {
+    "mnemo": {
+      "command": "mnemo"
+    }
+  }
+}
+```
+
+## 工具
+
+### `fact_store`
+
+读写结构化事实的主工具，支持 9 种操作：
+
+| 操作 | 说明 | 关键参数 |
+|------|------|----------|
+| `add` | 添加事实（自动去重，相似则合并） | `content`、`category`、`tags` |
+| `search` | 关键词搜索（FTS5 + Jaccard 重排序） | `query`、`category`、`min_trust`、`limit` |
+| `probe` | 查找某实体的所有事实 | `entity`、`min_trust`、`limit` |
+| `related` | 通过共享上下文查找关联事实 | `entity`、`min_trust`、`limit` |
+| `reason` | 多实体推理：查找与所有给定实体相关的事实 | `entities`、`min_trust`、`limit` |
+| `contradict` | 检测共享实体但内容冲突的事实对 | `limit` |
+| `update` | 更新事实的内容、标签、类别或信任分 | `fact_id`、`content`、`tags`、`category`、`trust_delta` |
+| `remove` | 按 ID 删除事实 | `fact_id` |
+| `list` | 按信任分浏览事实 | `category`、`min_trust`、`limit` |
+
+### `fact_feedback`
+
+使用事实后评分。好事实上升，坏事实下降。
+
+| 操作 | 效果 |
+|------|------|
+| `helpful` | +0.05 信任 |
+| `unhelpful` | -0.10 信任 |
+
+## 架构
+
+```
+┌───────────────────┐   stdio    ┌────────────┐   SQLite    ┌─────────────────────┐
+│   MCP Client      │◄─────────►│  mnemo     │◄───────────►│ ~/.mnemo/facts.db   │
+│ (Claude / Codex)  │   JSON    │  server    │             │                     │
+└───────────────────┘           └─────┬──────┘             │ 数据表：             │
+                                      │                    │   facts             │
+                               ┌──────┴──────┐             │   entities          │
+                               │             │             │   fact_entities     │
+                               │  Retriever  │  Security   │ 索引：              │
+                               │  (搜索、    │  (PII 扫描、 │   facts_fts (FTS5)  │
+                               │   探测、    │   注入检测)  │   idx_facts_trust   │
+                               │   推理)     │             │   idx_facts_category│
+                               └─────────────┘             └─────────────────────┘
+```
+
+## 类别
+
+| 类别 | 说明 | 衰减率 |
+|------|------|--------|
+| `identity` | 用户身份：姓名、角色、偏好 | 0.02/周 |
+| `coding_style` | 编码规范、命名、格式化 | 0.03/周 |
+| `tool_pref` | 工具和框架偏好 | 0.03/周 |
+| `workflow` | 开发工作流、CI/CD、Git 实践 | 0.02/周 |
+| `general` | 通用知识和其他事实 | 0.03/周 |
+
+## 开发
+
+```bash
+npm install
+npm test        # 运行测试（vitest）
+npm run build   # 编译 TypeScript
+npm start       # 启动 MCP 服务器
+```
+
+## 许可证
+
+[MIT](./LICENSE)

package/dist/init.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * mnemo init — 一键配置 mnemo 记忆系统
+ *
+ * 执行：
+ * 1. claude mcp add mnemo — 注册 MCP 服务器
+ * 2. ~/.claude/CLAUDE.md — 写入记忆使用规则
+ * 3. ~/.claude/settings.json — 添加 MCP 工具权限
+ */
+export {};

package/dist/init.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * mnemo init — 一键配置 mnemo 记忆系统
+ *
+ * 执行：
+ * 1. claude mcp add mnemo — 注册 MCP 服务器
+ * 2. ~/.claude/CLAUDE.md — 写入记忆使用规则
+ * 3. ~/.claude/settings.json — 添加 MCP 工具权限
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const CLAUDE_DIR = join(homedir(), '.claude');
+const CLAUDE_MD_PATH = join(CLAUDE_DIR, 'CLAUDE.md');
+const SETTINGS_PATH = join(CLAUDE_DIR, 'settings.json');
+const MEMORY_RULES = `
+# 记忆系统使用规则
+
+你有 mnemo 记忆工具（fact_store / fact_feedback），必须按以下规则使用：
+
+## 规则 1：搜索记忆（每次回复前）
+收到用户消息后，你必须先调用 \`fact_store(action="search", query="<用户消息的关键词>")\` 检索相关记忆。
+query 必须从用户消息中提取关键词，不要用固定模板。例如：
+- 用户说"我叫什么" → query="姓名 名字 叫什么"
+- 用户说"我喜欢什么语言" → query="编程语言 偏好 喜欢"
+搜索后根据结果自然回复，不要说"根据记忆"。
+
+## 规则 2：写入记忆
+用户说"记住"、"记下来"时，调用 \`fact_store(action="add", content="...", category="...")\`。
+- 先 search 检查是否已有相似事实，有则 update
+- category：identity / coding_style / tool_pref / workflow / general
+
+## 规则 3：反馈强化
+成功使用某条记忆时，调用 \`fact_feedback(action="helpful", fact_id=...)\`。
+`;
+const MCP_TOOLS = [
+    'mcp__mnemo__fact_store',
+    'mcp__mnemo__fact_feedback',
+];
+function log(msg) {
+    console.log(`\x1b[36m[mnemo]\x1b[0m ${msg}`);
+}
+function ok(msg) {
+    console.log(`\x1b[32m✓\x1b[0m ${msg}`);
+}
+function warn(msg) {
+    console.log(`\x1b[33m!\x1b[0m ${msg}`);
+}
+function fail(msg) {
+    console.log(`\x1b[31m✗\x1b[0m ${msg}`);
+}
+// -- Step 1: Register MCP server --
+function registerMcp(scope = 'user') {
+    log('注册 MCP 服务器...');
+    try {
+        execSync(`claude mcp add --scope ${scope} mnemo -- mnemo`, {
+            stdio: 'pipe',
+            timeout: 15000,
+        });
+        ok('MCP 服务器已注册 (claude mcp list 查看)');
+    }
+    catch (err) {
+        const stderr = err.stderr?.toString() || '';
+        if (stderr.includes('already exists') || stderr.includes('already registered')) {
+            warn('MCP 服务器已存在，跳过注册');
+        }
+        else {
+            fail(`注册失败: ${stderr.slice(0, 200)}`);
+            fail('请手动运行: claude mcp add mnemo -- mnemo');
+        }
+    }
+}
+// -- Step 2: Write CLAUDE.md --
+function writeClaudeMd() {
+    log('配置记忆使用规则...');
+    mkdirSync(CLAUDE_DIR, { recursive: true });
+    let existing = '';
+    if (existsSync(CLAUDE_MD_PATH)) {
+        existing = readFileSync(CLAUDE_MD_PATH, 'utf-8');
+        if (existing.includes('mnemo 记忆工具')) {
+            warn('CLAUDE.md 已包含 mnemo 规则，跳过');
+            return;
+        }
+    }
+    const merged = existing
+        ? existing.trimEnd() + '\n' + MEMORY_RULES
+        : MEMORY_RULES.trimStart();
+    writeFileSync(CLAUDE_MD_PATH, merged);
+    ok(`记忆规则已写入 ${CLAUDE_MD_PATH}`);
+}
+// -- Step 3: Update settings.json permissions --
+function updatePermissions() {
+    log('配置工具权限...');
+    mkdirSync(CLAUDE_DIR, { recursive: true });
+    let settings = {};
+    if (existsSync(SETTINGS_PATH)) {
+        try {
+            settings = JSON.parse(readFileSync(SETTINGS_PATH, 'utf-8'));
+        }
+        catch {
+            warn('settings.json 解析失败，将覆盖');
+        }
+    }
+    if (!settings.permissions)
+        settings.permissions = {};
+    if (!settings.permissions.allow)
+        settings.permissions.allow = [];
+    let added = 0;
+    for (const tool of MCP_TOOLS) {
+        if (!settings.permissions.allow.includes(tool)) {
+            settings.permissions.allow.push(tool);
+            added++;
+        }
+    }
+    if (added === 0) {
+        warn('权限已配置，跳过');
+        return;
+    }
+    writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+    ok(`已添加 ${added} 个工具权限到 ${SETTINGS_PATH}`);
+}
+// -- Main --
+function main() {
+    const args = process.argv.slice(2);
+    const scope = args.includes('--project') ? 'project' : 'user';
+    console.log('');
+    console.log('\x1b[1m  mnemo init — 一键配置记忆系统\x1b[0m');
+    console.log('');
+    registerMcp(scope);
+    writeClaudeMd();
+    updatePermissions();
+    console.log('');
+    ok('配置完成！重启 Claude Code 即可使用记忆系统。');
+    console.log('');
+}
+main();
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

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

package/dist/retriever.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 混合检索管线。
+ * 移植自 Ocean CLI FactRetriever，使用 better-sqlite3。
+ *
+ * 管线：FTS5 候选集 → Jaccard 重排序 → 信任评分加权 → 时间衰减
+ * 高级检索：probe/related/reason 基于 fact_entities 关联表
+ * 矛盾检测：实体重叠 + 内容差异
+ */
+import type { ScoredFact, Contradiction, SearchOptions, ContradictOptions, RetrieverOptions } from './types.js';
+import { MemoryStore } from './store.js';
+export declare class FactRetriever {
+    private store;
+    private db;
+    private ftsWeight;
+    private jaccardWeight;
+    private halfLifeDays;
+    /** category → 高频 tag 集合（从事实库自动学习，惰性初始化） */
+    private _categoryTagMap;
+    /** 中英术语对列表（从事实库自动学习，惰性初始化） */
+    private _cnEnPairs;
+    constructor(store: MemoryStore, options?: RetrieverOptions);
+    /** 主搜索：FTS5 → LIKE → 字符交叉 → 分类推断 → Jaccard → 信任评分 → 时间衰减 */
+    search(query: string, options?: SearchOptions): ScoredFact[];
+    /** 实体探测：查询某实体关联的所有事实 */
+    probe(entity: string, options?: SearchOptions): ScoredFact[];
+    /** 实体关联：查找与某实体共享上下文的其他事实 */
+    related(entity: string, options?: SearchOptions): ScoredFact[];
+    /** 多实体推理：查找同时关联多个实体的事实 */
+    reason(entities: string[], options?: SearchOptions): ScoredFact[];
+    /** 矛盾检测：实体重叠 + 内容差异 */
+    contradict(options?: ContradictOptions): Contradiction[];
+    /** Stage 1: FTS5 候选集 */
+    private ftsCandidates;
+    /** 简单分词：空格/下划线/中英文标点分割 + 小写 + 中文 bigram */
+    private tokenize;
+    /** Jaccard 相似度 */
+    private jaccardSimilarity;
+    /** Containment: a 中有多少比例的 token 出现在 b 中（不对称，衡量"查询被事实覆盖"的程度） */
+    private containmentScore;
+    /** 时间衰减: 0.5^(ageDays / halfLifeDays) */
+    private temporalDecay;
+    /** 判断查询是否为个人/身份相关（应触发 trust fallback） */
+    private isPersonalQuery;
+    /** Trust fallback — 查询无法匹配任何事实时，按信任评分返回 top-N */
+    private trustFallback;
+    /** LIKE fallback — FTS5 失败或中文查询时使用 */
+    private likeFallback;
+    /** 中文字符级 fallback — FTS5 和 LIKE 都失败时，用单字交叉匹配 */
+    private charOverlapFallback;
+    /** 分类推断 fallback — 根据查询关键词推断 category，返回该分类的高信任事实 */
+    private categoryInferFallback;
+    /** 从事实库自动学习 category → tag 映射（惰性初始化 + 缓存） */
+    private getCategoryTagMap;
+    /**
+     * 从事实库自动学习中英术语对（惰性初始化 + 缓存）。
+     * 两个来源：
+     * 1. 种子表：极小的核心 IT 术语对照（稳定不变，覆盖高频查询）
+     * 2. 事实库提取：括号注释/分隔符关联的高置信翻译对（自动增长）
+     * 歧义对（一个中文对应多个英文）自动丢弃。
+     */
+    private getCnEnPairs;
+    /** 添加候选对到 map */
+    private addPair;
+    /** 查询双语扩展：基于事实库自动学习的术语对照，将查询中的术语翻译为对端语言 */
+    private expandQueryBilingually;
+    /** 从查询内容推断 category — 基于事实库自动学习的 tag 映射 */
+    private inferCategory;
+    /** 检索追踪：递增 retrieval_count + top3 信任刷新（重置衰减时钟） */
+    private trackRetrieval;
+}