# Mnemosyne

> Mnemosyne V8 — 让 AI 记住重要的事 | Teaching AI to remember what matters | Governance-first memory system with WriteGate/ReadGate lifecycle

- **Type:** MCP server
- **Install:** `agentstack add mcp-nianpangzhi233-mnemosyne`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nianpangzhi233](https://agentstack.voostack.com/s/nianpangzhi233)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nianpangzhi233](https://github.com/nianpangzhi233)
- **Source:** https://github.com/nianpangzhi233/Mnemosyne
- **Website:** https://www.dreamfield.top

## Install

```sh
agentstack add mcp-nianpangzhi233-mnemosyne
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

---

  中文 · English · Report Bug · Request Feature

---

Mnemosyne

  让 AI 记住重要的事 — 一个记忆系统的思考与实验

  
  
  
  

---

## Features

- **Governance-first lifecycle** — RawEvent → Candidate → Evidence → ValidatedMemory → ContextPack. 没有捷径。
- **WriteGate** — 5 项拒绝检查，阻止未验证的 LLM 输出成为可信记忆。
- **ReadGate** — 5 项新鲜度/范围/风险过滤，控制什么能进入上下文。
- **Evidence-based verification** — 每条记忆必须有真实事件来源和佐证。
- **3 种接入方式** — CLI、MCP Server、REST API，共用同一套门控逻辑。
- **Auditable ContextPack** — 看到什么被接受了、什么被拒绝了、为什么。
- **Zero-dependency core** — 纯 Python + SQLite，不依赖 LLM、向量数据库或云服务。
- **Notebook-style Dashboard** — 温暖的纸质感 Streamlit 仪表盘。
- **8 个版本的演化** — 每个设计决策背后都是真实的踩坑。
- **反馈驱动 Confidence** — 每次使用记忆后反馈成功/失败，confidence 自动演化。低于阈值自动 stale/deprecate。
- **Tentative Promote（异步验证）** — 只有 source+scope 就能先晋升为 tentative 记忆，用 confidence=0.3 标记"待验证"。
- **记忆冲突检测** — 自动发现重复和关键词冲突（can/cannot、works/broken），标记矛盾记忆。
- **多 Agent 共享记忆** — 按 project_id 共享，agent_id 只做溯源。同一项目下的 Agent 共享已验证记忆。

---

## 记忆 ≠ 上下文

这是我们在构建这个系统过程中得到的最重要的一个认知。

很多人把"给 LLM 塞更多上下文"等同于"让 AI 有记忆"。这是错的。

**上下文是你喂给 LLM 的东西。记忆是 LLM 自己生成、并且被验证过的东西。**

区别在哪？

LLM 是一个概率模型。你问它"torch 2.11.0 在 Windows 上能用吗"，它会基于训练数据概率生成一个回答。这个回答可能是对的，也可能是错的——但 LLM 自己不知道，因为它每次回答都是概率采样。

如果把这个回答直接存起来当成"记忆"，下次遇到类似问题时注入上下文——你就把一个**未验证的概率猜测**变成了**被系统信任的事实**。这就是"幻觉固化"：LLM 的错误回答通过记忆系统获得了不应有的权威性。

**真正的记忆必须经过验证。**

这就是 Mnemosyne V8 存在的原因。它不存储 LLM 说了什么——它存储的是**从事实中提炼、经过证据验证、通过门控审核**的东西。

```text
LLM 说了一句话 → 那只是概率输出，不是记忆
LLM 说了一句话 + 有真实事件来源 + 有证据支撑 + 通过了验证 → 这才是记忆
```

## 为什么是 V8？

这个项目不是一次设计到位的。它经历了 8 个大版本的迭代，每个版本都踩了真实的坑。

```text
V1 — 简单的键值存储。能记住东西，但没有结构。
      问题：存了就存了，没有验证，没有淘汰。

V2 — 加入向量搜索。能语义检索了。
      问题：搜索不等于记忆。top-k 拼接不是上下文治理。

V3 — 知识图谱。节点和边，语义关系。
      问题：图谱会越来越乱。LLM 生成的边不可靠。

V4 — 抽象层重构。解耦存储、嵌入、调度。
      问题：架构变好了，但数据治理问题没解决。

V5 — 记忆进化引擎。做梦机制，自动提取经验。
      问题：LLM 自我总结还是不可靠。AI 自己审自己等于没审。

V6 — MCP 集成。让 AI Agent 能读写记忆。
      问题：接入了但缺少治理。Agent 想写什么就写什么。

V7 — Skill 系统。把经验提炼为可复用技能。
      问题：技能质量参差不齐，缺少验证闭环。

V8 — 彻底的治理优先。
      不再信任 LLM 的输出。一切从 RawEvent（原始事件）开始，
      LLM 生成的内容只能是 Candidate（候选人），
      必须挂 Evidence（证据）并通过 WriteGate（写入门控），
      才能晋升为 ValidatedMemory（已验证记忆）。
```

V8 不是一个渐进改良。它是对前七个版本的反思：**如果一个记忆系统不能区分"LLM 猜的"和"被验证的事实"，它就不是记忆系统，只是一个带搜索的剪贴板。**

## V8 核心架构

### 生命周期流水线

```text
RawEvent → Candidate → Evidence → ValidatedMemory → ContextPack
```

每一步都有门控，没有捷径。

```mermaid
graph LR
    RE["`**RawEvent**
    原始事件`"] -->|source_event_ids| CA["`**Candidate**
    候选人`"]
    EV["`**Evidence**
    证据`"] -->|supports / weakens| CA
    CA -->|"WriteGate ✓"| VM["`**ValidatedMemory**
    已验证记忆`"]
    VM -->|"ReadGate ✓"| CP["`**ContextPack**
    受控上下文`"]

    style RE fill:#2c2c2c,color:#f7f3eb
    style CA fill:#c4956a,color:#fff
    style EV fill:#8b7355,color:#fff
    style VM fill:#4a7c59,color:#fff
    style CP fill:#2c5f7c,color:#fff
```

- **RawEvent**：不可变的事实记录。谁做了什么，什么时间，什么结果。地基。
- **Candidate**：LLM 或人工从 RawEvent 中提炼的待验证声明。
- **Evidence**：附加在 Candidate 上的佐证或反驳（`supports` / `weakens` / `contradicts` / `neutral`）。
- **ValidatedMemory**：通过 WriteGate 的 Candidate。只有这个状态才能被注入上下文。
- **ContextPack**：通过 ReadGate 筛选后组装的上下文包。包含被接受和被拒绝的记忆及原因。

### WriteGate — 不是什么都能变成记忆

| 拒绝原因 | 含义 |
|---------|------|
| `missing_source` | 没有挂载 RawEvent 来源 |
| `missing_scope` | 没有归属范围 |
| `missing_supporting_evidence` | 没有佐证 |
| `contradicting_evidence` | 存在反驳证据 |
| `missing_procedural_evidence` | 流程类记忆缺少测试结果 |

**全部通过才能晋升。** 这保证了每条记忆都是可溯源、有证据、有归属的。

### ReadGate — 不是什么都能进入上下文

| 拒绝原因 | 含义 |
|---------|------|
| `stale` | 新鲜度低于阈值 |
| `status_blocked` | 状态不是 validated 或 promoted |
| `risk_blocked` | 风险等级超出策略允许范围 |
| `scope_mismatch` | 范围与当前请求不匹配 |
| `no_task_match` | 任务关键词与记忆内容无交集 |
| `low_confidence` | Confidence 低于策略阈值（默认 0.3） |

被拒绝的记忆会出现在 ContextPack 的 `rejected` 列表中，附上拒绝原因。

### 生命周期降级

```text
promote → tentative → demote / stale / deprecate
```

- **tentative**：只有 source+scope 就能晋升，confidence=0.3。"先用着，等反馈"。
- **demote**：暂时从注入列表移除，保留数据。"暂停使用"。
- **stale**：标记过时，新鲜度归零。"可能不适用了"。
- **deprecate**：永久废弃。"被证明是错的"。

不是所有错误都需要删除，有些只需要标记"慎用"。

### 反馈驱动 Confidence

每条记忆都有一个 confidence 分数（0-1），通过真实使用反馈自动演化：

```text
feedback.record(memory_id, outcome="success")  → confidence += 0.05
feedback.record(memory_id, outcome="failure")  → confidence -= 0.1
```

- confidence ≤ 0.15 → 自动 stale
- 连续 3 次以上 failure → 自动 deprecate

**判断权交给调用方。** Agent 任务千奇百怪，V8 不自动推断成功/失败，由调用方显式报告。

### 记忆冲突检测

```text
conflict.scan(scope) → 检测重复 + 关键词冲突
```

- **重复检测**：content 完全相同的记忆
- **关键词冲突**：can/cannot、works/broken、support/not support 等配对词同时出现

冲突被写入 `memory_conflicts` 表，不会自动删除任何记忆——标记即足够。

### 多 Agent 共享

```text
scope.list_agents(project_id)  → 列出项目下所有 Agent
scope.share_memory(memory_id)  → 标记为项目可见
```

同项目共享已验证记忆，agent_id 只做溯源不做权限控制。不同项目用不同 project_id 隔离。

## 快速上手

### 安装

```bash
git clone https://github.com/nianpangzhi233/Mnemosyne.git
cd Mnemosyne
pip install -e .
```

### 5 分钟演示

```bash
$env:PYTHONPATH = "v8/src"
```

**1. 记录原始事件**

```bash
python -m v8_memory.cli --db "v8/data/v8.db" event add \
  --type tool_error \
  --actor agent \
  --content "PowerShell rejected Bash heredoc syntax." \
  --scope-item project_id=demo --scope-item session_id=test
```

**2. 从事件中提炼候选人**

```bash
python -m v8_memory.cli --db "v8/data/v8.db" candidate add \
  --type claim \
  --content "PowerShell does not support Bash heredoc." \
  --sources  \
  --scope-item project_id=demo \
  --trigger "debug PowerShell inline command"
```

**3. 挂上证据**

```bash
python -m v8_memory.cli --db "v8/data/v8.db" evidence add \
  --target  \
  --type task_success --polarity supports \
  --content "Using a PowerShell-compatible command fixed the issue." \
  --sources 
```

**4. 晋升为已验证记忆**

```bash
python -m v8_memory.cli --db "v8/data/v8.db" lifecycle promote \
  --candidate 
```

**5. 构建上下文包**

```bash
python -m v8_memory.cli --db "v8/data/v8.db" context build \
  --task "debug PowerShell inline command" \
  --scope-item project_id=demo --pretty
```

输出：

```json
{
  "items": [
    {
      "id": "mem_...",
      "type": "claim",
      "content": "PowerShell does not support Bash heredoc.",
      "status": "validated",
      "source_events": [
        { "id": "evt_...", "event_type": "tool_error", "content": "PowerShell rejected Bash heredoc syntax." }
      ],
      "evidence": [
        { "type": "task_success", "polarity": "supports", "content": "Using a PowerShell-compatible command fixed the issue." }
      ]
    }
  ],
  "rejected": [],
  "warnings": []
}
```

每条记忆带着来源事件和证据。**可审计、可追溯、可拒绝。**

## 接入方式

三种接入方式，共用同一套门控逻辑：

### CLI

```bash
$env:PYTHONPATH = "v8/src"
python -m v8_memory.cli --db "v8/data/v8.db"  [options]
```

### MCP Server（AI Agent 集成）

V8 MCP 工具以 `v8_` 前缀暴露，19 个工具覆盖完整生命周期。连接时自动加载 `instructions` 指引。

**支持所有 MCP 兼容客户端：** Claude Code、Claude Desktop、Cursor、Windsurf、VS Code + Copilot、Hermes Agent、OpenClaw、Cherry Studio、OpenCode 等。

```text
v8_event_add → v8_candidate_add → v8_evidence_add → v8_lifecycle_promote → v8_context_build
```

各平台配置方法见 [docs/agent-integration.md](docs/agent-integration.md)。

### REST API

```bash
start-v8-api.cmd

curl -X POST http://127.0.0.1:8979/api/v8/events \
  -H "Content-Type: application/json" \
  -d '{"event_type":"tool_error","actor":"agent","content":"...","scope":{"project_id":"demo"}}'
```

完整端点列表见 [v8/README.md](v8/README.md)。

## 设计决策日志

### 为什么用 SQLite 不用 PostgreSQL？

Mnemosyne 的场景是**单用户本地 Agent**，不是多租户 SaaS。SQLite 零配置、零运维、单文件可拷贝。备份就是 `cp v8/data/v8.db backup/`。等真有多租户需求再迁移。过早优化是万恶之源。

### 为什么 Evidence 是独立实体而不是 Candidate 的属性？

同一条证据可能关联多个 Candidate。一个 RawEvent（"torch 2.11.0 在 Windows 上 DLL 崩溃"）可以同时作为多条记忆的证据来源。如果证据只是子字段，就无法表达多对多关系，也无法做证据级溯源。

### 为什么 ContextPack 要包含被拒绝的记忆？

**拒绝本身就是信息。** 知道"哪些记忆被拒绝了、为什么"比只看通过的记忆更有价值。和代码审查中查看 rejected PR 的理由同理。

### 为什么不允许直接写记忆？

LLM 是概率模型。它自信地说出的"经验"可能是幻觉。如果允许直接写入记忆，系统会被未验证的概率输出污染。这就是 V1-V7 最大的教训：**不能信任 LLM 的自我总结**。

### 为什么 WriteGate 用 Python callable 不用 YAML？

验证逻辑本质是代码——查数据库、解析内容、匹配关键词。YAML 只是壳，最终还是要写 Python 函数。与其引入 YAML 解析依赖再回调 Python，不如直接注册 Python callable。简单、直接、无依赖。

## Dashboard

**在线演示：** [https://nianpangzhi233.github.io/Mnemosyne/](https://nianpangzhi233.github.io/Mnemosyne/)

笔记本风格只读仪表盘——纸色背景、墨色文字、横格线分隔。记忆系统应该是温暖的、有质感的。

  

本地运行（Streamlit）：

```bash
streamlit run scripts/dashboard/app_v8.py --server.port 8501
```

Web Dashboard（纯 HTML + JS，零依赖）：

```bash
# 直接打开
start scripts/dashboard/web/index.html
# 或启动 REST API 后访问（实时数据）
start-v8-api.cmd
# 然后修改 index.html 中的 API_BASE 为 http://127.0.0.1:8979/api/v8
```

## 项目结构

```text
Mnemosyne/
├── v8/
│   ├── src/v8_memory/       # V8 核心包
│   │   ├── models.py        # 数据模型
│   │   ├── store.py         # SQLite 存储层
│   │   ├── services.py      # 业务逻辑
│   │   ├── gates.py         # WriteGate / ReadGate
│   │   ├── lifecycle.py     # 生命周期管理
│   │   ├── context.py       # ContextPack 构建
│   │   ├── feedback.py      # 反馈驱动 confidence 演化
│   │   ├── conflict.py      # 记忆冲突检测
│   │   ├── agent_scope.py   # 多 Agent 共享记忆
│   │   ├── gate_steps.py    # WriteGate 自定义步骤示例
│   │   └── cli.py           # 命令行接口
│   ├── scripts/             # 功能测试脚本
│   └── README.md            # V8 详细技术文档
├── scripts/
│   ├── dashboard/           # Streamlit 仪表盘
│   ├── api/                 # REST API
│   ├── mcp_server/          # MCP Server
│   └── core/                # 共享工具
├── tests/                   # 测试套件
├── docs/                    # 架构文档和设计记录
├── engine/                  # 辅助脚本
└── pyproject.toml           # 包配置
```

## 测试

```bash
python -m unittest discover tests
```

- `test_v8_mvp.py` — 内核生命周期测试
- `test_v8_feedback.py` — 反馈/conflict/scope/tentative/gate 测试
- `test_gate_steps.py` — WriteGate 自定义步骤测试
- `test_v8_rest_api.py` — REST API 端点测试
- `test_v8_demo.py` — 端到端演示验证
- `test_v8_dashboard_store.py` — Dashboard 数据层测试
- `test_mcp_v8_surface.py` — MCP 工具接口测试

## 运行条件

- Python 3.10+
- Windows / macOS / Linux
- 可选：PyTorch + sentence-transformers（向量搜索，V8 内核不依赖）
- 可选：FastAPI + uvicorn（REST API）
- 可选：Streamlit（Dashboard）

## 路线图

- [x] 记忆冲突自动检测（多条记忆互相矛盾时主动标记）
- [x] 多 Agent 共享记忆（跨 Agent 的 scope 隔离与共享）
- [x] 反馈驱动 Confidence 演化
- [x] Tentative Promote（异步验证）
- [ ] LLM 驱动的自动 Evidence 生成（保持人工审核）
- [x] Web Dashboard（纯 HTML + JS，部署到 GitHub Pages）
- [ ] LLM 驱动的自动 Evidence 生成（保持人工审核）

## 参与贡献

欢迎提交 Issue 和 Pull Request。

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feature/your-feature`
3. 提交改动：`git commit -m "Add your feature"`
4. 推送分支：`git push origin feature/your-feature`
5. 提交 Pull Request

请确保所有测试通过：`python -m unittest discover tests`

## 更新日志

见 [CHANGELOG.md](CHANGELOG.md)。

## 致谢

这个项目是一个人在下班后的晚上和周末鼓捣出来的。白天是小学老师，教 47 个一年级小朋友。晚上是程序员，教一个 AI 怎么记住重要的事。

如果你觉得这个项目有意思，给个 Star 就是对我最大的鼓励。

## License

[MIT](LICENSE)

---

Mnemosyne

  Teaching AI to remember what matters — a memory system built through experimentation

  
  
  
  

---

## Features

- **Governance-first lifecycle** — RawEvent → Candidate → Evidence → ValidatedMemory → ContextPack. No shortcuts.
- **WriteGate** — 5 rejection checks prevent unverified LLM output from becoming trusted memory.
- **ReadGate** — 5 freshness/scope/risk filters control what enters the LLM context.
- **Evidence-based verification** — Every memory backed by real events and supporting evidence.
- **3 integration paths** — CLI, MCP Server, REST API. Same gate logic everywhere.
- **Auditable ContextPack** — See what was accepted, rejected, and why.
- **Zero-dependency core** — Pure Python + SQLite. No LLM, no vector DB, no cloud.
- **Notebook-style Dashboard** — Warm, paper-textured Streamlit UI.
- **8-version evolution** — Every design decision backed by real failures.
- **Feedback-driven Confidence** — Report success/failure after using a memory; confidence auto-evolves. Auto-stale/deprecate below threshold.
- **Tentative Promote (async verification)** — Promote with only source+scope to tentative (confidence=0.3), verified later through real usage.
- **Memory Conflict Detection** — Auto-detect duplicates and keyword clashes (can/cannot, works/broken). Flag contradictory memories.
- **Multi-Agent Shared Memory** — Share by project_id, trace by agent_id. Agents in the same project share validated memories.

---

## Memory ≠ Context

This is the single most important insight from building this system.

Many people equate "stuffing more context into an LLM" with "giving AI memory." This is wrong.

**Context is what you feed to an LLM. Memory is what the LLM generates and then gets verified.**

Here's the difference:

An LLM is a probabilistic model. Ask it "does torch 2.11.0 work on Windows?" and it'll give you an answer based on training data probabilities. That answer might be right or wrong — the LLM doesn't know, because every response is probabilistic sampling.

If you store that answer directly as "memory" and inject it as context next time a similar question comes up — you've just turned an **unverified probabilistic guess** into a **system-trusted fact**. This is "hallucination solidification": LLM errors gaining undeserved authority through the memory system.

**Real memory must be verified.**

That's why Mnemosyne V8 exists. It doesn't store what the LLM said — it stores things **extracted from facts, backed by evidence, approved through gates**.

```text
LLM says something → that's just probabilistic output, not memory
LLM says something + has real event sources + has evidence + passed verification → THAT is memory
```

## Why V8?

This project wasn't designed in one shot. It went through 8 major versions, each learning from real failures.

```text
V1 — Simple key-value store. Could remember things, no structure.
      Problem: stored forever, no verification, no eviction.

V2 — Added vector search. Semantic retrieval worked.
      Problem: search ≠ memory. Top-k concatenation is not context governance.

V3 — Knowledge graph. Nodes and edges, semantic relationships.
      Problem: graphs get messy. LLM-generated edges are unreliable.

V4 — Abstraction layer refactor. Decoupled storage, embedding, scheduling.
      Problem: better architecture, same data governance problems.

V5 — Memory evolution engine. Dream mechanism, automatic experience extraction.
      Problem: LLM self-summarization is unreliable. AI auditing itself = no audit.

V6 — MCP integration. Let AI agents read/write memory.
      Problem: connected but ungoverned. Agents write whatever they want.

V7 — Skill system. Distill experiences into reusable skills.
      Problem: skill quality varied, no verification loop.

V8 — Governance-first. From the ground up.
      No longer trusts LLM output. Everything starts from RawEvent.
      LLM-generated content can only be a Candidate.
      Must attach Evidence and pass WriteGate
      to become ValidatedMemory.
```

V8 is not an incremental improvement. It's a reflection on seven previous versions: **if a memory system can't distinguish "LLM guessed it" from "verified fact", it's not a memory system — it's a clipboard with search.**

## V8 Core Architecture

### Lifecycle Pipeline

```text
RawEvent → Candidate → Evidence → ValidatedMemory → ContextPack
```

Every step has a gate. No shortcuts.

```mermaid
graph LR
    RE["`**RawEvent**
    ground truth`"] -->|source_event_ids| CA["`**Candidate**
    unverified claim`"]
    EV["`**Evidence**
    proof`"] -->|supports / weakens| CA
    CA -->|"WriteGate ✓"| VM["`**ValidatedMemory**
    verified memory`"]
    VM -->|"ReadGate ✓"| CP["`**ContextPack**
    governed context`"]

    style RE fill:#2c2c2c,color:#f7f3eb
    style CA fill:#c4956a,color:#fff
    style EV fill:#8b7355,color:#fff
    style VM fill:#4a7c59,color:#fff
    style CP fill:#2c5f7c,color:#fff
```

### WriteGate — Not everything becomes memory

| Rejection Reason | Meaning |
|-----------------|---------|
| `missing_source` | No RawEvent sources attached |
| `missing_scope` | No scope (project, session) assigned |
| `missing_supporting_evidence` | No supporting evidence |
| `contradicting_evidence` | Contradicting evidence exists |
| `missing_procedural_evidence` | Procedure-type candidate lacks test result evidence |

**All checks must pass for promotion.** Every memory is traceable, evidenced, and scoped.

### ReadGate

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nianpangzhi233](https://github.com/nianpangzhi233)
- **Source:** [nianpangzhi233/Mnemosyne](https://github.com/nianpangzhi233/Mnemosyne)
- **License:** MIT
- **Homepage:** https://www.dreamfield.top

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-nianpangzhi233-mnemosyne
- Seller: https://agentstack.voostack.com/s/nianpangzhi233
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.