| 記憶 API | Memory / AsyncMemory / MemoryClient，方法面齊全：add get get_all search update delete delete_all history reset close from_config。 |
| 四維作用域 | user_id / agent_id / run_id / app_id —— 做的是實體隔離：每個作用域一個 SQLite 檔案，而不是共享列上加過濾條件。 |
| 過濾語言 | eq ne gt gte lt lte in nin contains icontains wildcard，支援 AND/OR/NOT 任意巢狀。 |
| 單遍 ADD-only 抽取 | 每次寫入一次模型呼叫，記憶只累加、不覆蓋。因為「不改寫」，壞抽取只會引入雜訊，永遠不會毀掉真事實。 |
| 圖記憶常開 | 實體連結與多跳遍歷由同一個 SQLite 檔案承載，不需要任何外部圖資料庫。 |
| 多模態攝入 | 支援 OpenAI / Anthropic / Gemini 三種圖片內容格式（含音訊）。配了視覺模型就生成描述，沒配就存引用——不丟東西。 |
| 多信號檢索 | 語意 + BM25 關鍵字 + 實體圖 + 時序 + 標籤五路融合，帶標定過的相關性下限與詞面兜底。 |
| 時序推理 | 觀測日期、相對時間解析、過期語意，以及按實體的版本鏈。 |
| 分層記憶 | 熱 / 溫 / 冷三層 + 遺忘經濟學 (economic forgetting)：低價值記憶降級壓縮，絕不靜默刪除。 |
| 無損壓縮（AIC） | 把一條記憶壓成「指標 + 結構化事實 + 內容原子」。數字、日期、金額、型號在任何層級都完整保留；expand() 逐字取回原文並校驗哈希。 |
| 哈希鏈審計賬本 | SHA-256 鏈式賬本；verify_integrity() 能發現篡改並指出具體是哪一條被改。 |
| 非同步 API 與事件 | AsyncMemory 支撐高吞吐寫入，加上持久化操作日誌，讓「已受理的寫入」跨程序可查。 |
| 中文優化 | 雙字分詞 (bigram) + FTS5 + 內建同義詞辭典，同時完整支援拉丁文字。 |
| 安全公證器 | 寫入前偵測憑據、不可見 Unicode 與 HTML 注入，並做欄位級脫敏 (field-level redaction)。 |
---
## 🔌 支援的整合
所有適配器都是可選的。標 **stdlib** 的不需要任何三方套件——直接用 `urllib` 走 HTTP；標 **sdk** 的惰性載入 SDK，缺套件時會明確告訴你裝哪個。
### LLM 供應商（20）
| 傳輸方式 | 供應商 |
| --- | --- |
| **stdlib HTTP** | `openai` `openai_structured` `azure_openai` `azure_openai_structured` `ollama` `anthropic` `gemini` `groq` `together` `deepseek` `minimax` `xai` `sarvam` `openrouter` `litellm` `lmstudio` `vllm` |
| **sdk** | `langchain` `aws_bedrock` |
| **內建** | `rules` —— 確定性離線抽取器，所以完全不配模型也能 `add()` |
### 嵌入模型（13）
| 傳輸方式 | 供應商 |
| --- | --- |
| **stdlib HTTP** | `openai` `azure_openai` `ollama` `gemini` `vertexai` `together` `lmstudio` `huggingface` |
| **sdk** | `fastembed` `langchain` `aws_bedrock` |
| **內建** | `builtin`（128 維、零依賴、確定性）· `hashing`（任意維度、離線） |
### 向量庫（28）
| 傳輸方式 | 向量庫 |
| --- | --- |
| **內嵌** | `builtin`（一個 SQLite 檔案同時存記憶和向量）· `memory` · `generic`（宣告式 REST） |
| **stdlib HTTP** | `qdrant` `pinecone` `elasticsearch` `opensearch` `weaviate` `upstash_vector` `turbopuffer` |
| **sdk** | `chroma` `pgvector` `milvus` `mongodb` `redis` `valkey` `azure_ai_search` `azure_mysql` `baidu` `cassandra` `databricks` `faiss` `langchain` `neptune` `oracledb` `s3_vectors` `supabase` `vertex_ai_vector_search` |
### 圖資料庫（6）
`builtin`（原生 SQLite 三元組）· `neo4j` · `memgraph` · `neptune` · `kuzu` · `sparql`（任意 SPARQL 1.1 端點）
### 重排器（5）
`llm` · `cohere` · `zero_entropy` · `huggingface` · `sentence_transformer`
### 框架適配
LangChain · LlamaIndex · CrewAI · Dify · n8n · Vercel AI SDK · Ollama · MCP（stdio + Streamable HTTP）
---
## 🛠 MCP 伺服器
以 stdio JSON-RPC 執行：
```bash
export MNEMOSYNE_MCP_TOKEN="your-secret-token" # 可選，但建議設定
python -m mnemosyne.webui.mcp_server --brain-dir ./mem --namespace default
```
**52 個工具** —— 41 個原生工具（其中 21 個是 8.1.0 新增：9 個記憶形成層 + 12 個記憶執行層），外加 11 個沿用通行 Agent 記憶工具命名的工具，已有的 MCP 宿主（Claude Desktop、Hermes Agent 等）不必改寫工具定義就能直接指向 Mnemosyne。
**原生 · 檢索與治理（23）：**
| 工具 | 說明 |
| --- | --- |
| `retain` | 寫入一條記憶 |
| `recall` | 檢索記憶 |
| `retain_batch` | 批次寫入，約快 15× |
| `forget` | 遺忘一條記憶 —— 可用 id，也可用自然語言查詢定位 |
| `capsule` | 把一條記憶壓成 指標 + 事實 + 原子 |
| `expand` | 逐字取回膠囊原文 |
| `recall_health` | 唯讀的召回品質指標 |
| `consolidate` | 把近似重複的記憶合併成一條代表性記憶 |
| `reflect` | 統計、高頻實體、衝突偵測、認知模式 |
| `dedup` | 偵測重複與近似重複 |
| `graph_query` | 知識圖譜遍歷 |
| `temporal_query` | 版本鏈查詢 |
| `list_projects` | 列出隔離的專案 |
| `doctor` | 健康檢查 —— 完整性、筆數、磁碟、後端狀態 |
| `stats` | 執行統計 |
| `audit` | 審計鏈查詢 |
| `confidence_history` | 可信度軌跡 |
| `memory/export-v1` | 依 Memory Exchange Protocol 匯出 |
| `memory/import-v1` | 依 Memory Exchange Protocol 匯入 |
| `memory/claim` | 認領外部匯出的記憶 |
| `memory_export-v1` | `memory/export-v1` 的別名（供不接受 `/` 的用戶端使用） |
| `memory_import-v1` | `memory/import-v1` 的別名（供不接受 `/` 的用戶端使用） |
| `memory_claim` | `memory/claim` 的別名（供不接受 `/` 的用戶端使用） |
**原生 · 記憶形成層（9，v8.1.0 新增）：**
| 工具 | 說明 |
| --- | --- |
| `session_summarize` | 會話摘要：七要素 + 錨點原文保留，未決事項獨立成條 |
| `session_recall` | 召回摘要與未決事項，供下次對話主動追問 |
| `conflict_resolve` | 六類衝突判定 + 四操作；`scope=audit` 做全庫審計（只報真衝突） |
| `task_record` | 記錄任務事實（只追加），依 `goal_type` 支撐同類任務檢索 |
| `playbook_save` | 沉澱經驗，**強制** `preconditions` 三件套 |
| `playbook_recall` | 檢索候選經驗並做前置條件校驗，回傳 `applicable` / `blocked_by` |
| `code_change_record` | 記錄變更事件：意圖、約束、影響面、放棄的方案 |
| `code_archaeology` | 代碼考古 / 坑位預警（傳 `intent` 即轉為坑位檢查） |
| `memory_policy` | 敏感度判定、寫入准入、存量高危記憶審計 |
**原生 · 記憶執行層（12，v8.1.0 新增）：**
| 工具 | 說明 |
| --- | --- |
| `profile_card` | 使用者畫像卡：三段分級（穩定身份 / 偏好與約束 / 當前情境）+ 未決事項，可直接拼進 system prompt。`max_tokens` 是硬上限——超預算按「情境→未決→偏好」逐段裁，絕不截斷單條。 |
| `memory_inject` | 上下文注入流水線：查詢構造 → 四路召回 → RRF 融合 → 重排 → 預算內注入，回傳可直接注入的 text 加四段配額帳目。給模型準備上下文時比 `recall` 更合適。 |
| `recall_catalog` | 漸進披露·目錄層：只回傳標題 + 一句話 + 展開成本，不回傳正文。先看目錄判斷哪幾條相關，再對 1~2 條調 `expand_memory`——注入成本從 O(全部) 降到 O(目錄 + 少量)。 |
| `expand_memory` | 漸進披露·展開：取一條記憶的正文 + 統一信封 + 圖鄰居 + 證據鏈。與 `recall_catalog` 配對；鄰居來自知識圖譜，所以「當時這個決定影響了哪些模組」是可回答的。 |
| `memory_envelope` | 統一記憶信封：八類分類 + 四維 scope + 證據鏈 + 雙時間軸 + TTL + SPO 結構。省略 `memory_id` 時回傳全庫八類分佈統計。 |
| `memory_consolidate` | 鞏固三路徑：情境→語意、情境→程序性、失敗→負記憶。冪等——同一批來源不會重複產生。 |
| `memory_metrics` | 度量指標：Chat 5 項 + Working 4 項 + Coding 4 項。誠實原則——資料不足回傳 `{value:null, status:"insufficient_data"}` 而不是填 0，0 和「沒資料」是兩件事。 |
| `memory_cascade_delete` | 級聯刪除：軟刪原始 → 失效派生結論 → 清檢索快取 → 依賴摘要標 stale。`hard=true` 才物理刪除；先跑 `dry_run=true` 看 dependents。 |
| `memory_mask` | 遮罩：把正文替換為佔位符但保留記錄骨架，保持上下文長度與前綴不變（不破壞 KV-Cache 複用）。使用者說「別記這個」時優先用遮罩。`action=unmask` 可撤銷。 |
| `topic_summarize` | L3 主題摘要：把同一 project 下的多條 L2 會話摘要合併成「這個專案現在處於什麼狀態」。合併規則確定性（goal 取最新、decisions 累積、pending 只留最新）。`persist=true` 落庫並記錄 `pointer.children`。 |
| `memory_trace` | 指標鏈回溯：沿 L3→L2→L1 回溯，回傳每層內容、覆蓋的輪次區間與 `message_ids`。回答「這條結論是從哪句話來的」。 |
| `memory_hot_path` | 熱路徑緩衝：`action=enable` 開啟非同步寫入（熱路徑只入隊）；`action=status` 檢視佇列與統計；`action=flush` 等佇列落碟——寫完立刻讀之前必須 flush 的讀一致性屏障。 |
**客戶端相容（11）：**
| 工具 | 說明 |
| --- | --- |
| `add_memory` | 為使用者／代理儲存文字或對話歷史 |
| `search_memories` | 帶過濾條件的語意檢索 |
| `get_memories` | 結構化過濾 + 分頁列表 |
| `get_memory` | 依 id 取一條 |
| `update_memory` | 覆蓋文字和／或中繼資料 |
| `delete_memory` | 刪除一條 |
| `delete_all_memories` | 清空某個作用域 |
| `delete_entities` | 刪除實體並級聯 |
| `list_entities` | 列出 users/agents/apps/runs |
| `list_events` | 列出記憶操作 |
| `get_event_status` | 輪詢非同步操作 |
---
## 🌐 自託管 REST API
一個程序、一個埠，支援 `X-API-Key` / `Bearer` / `Token` 三種鑑權寫法，控制台與 API 共用同一個監聽。
| 方法 | 路徑 | 用途 |
| --- | --- | --- |
| `GET` | `/v1/status/` | 存活探針 + 即時設定報告 |
| `GET` | `/v1/providers/` | 所有供應商及其目前可用性 |
| `POST` | `/v3/memories/add/` | 抽取並寫入（非同步，回傳事件 id） |
| `POST` | `/v3/memories/search/` | 語意檢索 |
| `POST` | `/v3/memories/get-all/` | 帶過濾的列表 |
| `GET` / `PUT` / `DELETE` | `/v3/memories/{id}/` | 取 / 改 / 刪一條 |
| `DELETE` | `/v3/memories/` | 清空作用域 |
| `GET` | `/v3/memories/{id}/history/` | 變更歷史 |
| `GET` | `/v1/event/{id}/` · `/v1/events/` | 輪詢 / 列出操作 |
| `GET` / `DELETE` | `/v2/entities/` | 列出 / 刪除作用域 |
| `POST` | `/v3/graph/{add,search,get-all,delete-all}/` | 圖記憶 |
| `POST` | `/v1/capsule/` · `/v1/expand/` | 無損壓縮 |
| `GET` | `/v1/integrity/` | 賬本校驗 |
| `GET` / `POST` / `DELETE` | `/v1/keys/` | API 金鑰管理 |
---
## 🧠 Python API
```python
from mnemosyne import Memory, AsyncMemory, MemoryClient
# --- 抽取 / 作用域 / 過濾 -----------------------------------------------------
m = Memory()
m.add([{"role": "user", "content": "我 2023 年搬到了柏林。"}],
user_id="alice", metadata={"source": "onboarding"},
observation_date="2023-06-01")
m.add("發票號是 INV-2024-001。", user_id="alice", immutable=True)
hits = m.search("使用者住在哪",
filters={"user_id": "alice",
"AND": [{"source": {"eq": "onboarding"}}]},
top_k=5, threshold=0.1, rerank=False, explain=True)
# --- 多模態 -------------------------------------------------------------------
m.add([{"role": "user", "content": [
{"type": "text", "text": "我的新桌面。"},
{"type": "image_url", "image_url": {"url": "https://example.com/desk.jpg"}},
]}], user_id="alice")
# --- 圖記憶 -------------------------------------------------------------------
m.graph_add("賈伯斯在庫比蒂諾創立了蘋果。", user_id="alice")
m.graph_search("蘋果", filters={"user_id": "alice"})
# --- 非同步與事件 -------------------------------------------------------------
async def ingest():
am = AsyncMemory()
await am.add_many([{"messages": t, "options": {"user_id": "alice"}}
for t in transcripts])
```
`Memory` / `AsyncMemory` / `MemoryClient` 同時接受其他記憶庫通行的呼叫形態，所以已有程式碼只需改一行 import 即可切換。見 [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md)。
引擎自身的能力掛在同一個物件上：
```python
from mnemosyne import MemoryBrain
brain = MemoryBrain("./memories", enable_embeddings=True)
brain.ensure_init()
brain.retain("他那台筆記型電腦是 ASUS VivoBook Pro 14", fast=True)
results = brain.recall("那台機器的設定是什麼", k=5)
results, cost = brain.recall("那台機器的設定", k=5, budget_tokens=100)
cap = brain.capsule("
