engram

Engram

AI 跨工具長期記憶系統 — 讓 Claude Code 與 Antigravity 共享長期記憶。

特性

• 🔍 混合檢索：向量搜尋（cosine）+ BM25 全文搜尋 + RRF Fusion
• 🧠 8 步流水線：RecencyBoost → ImportanceWeight → LengthNorm → TimeDecay → NoiseFilter → MMR
• ⏳ Weibull 衰減：Core / Working / Peripheral 三層 Tier，重要記憶不衰退
• 🔗 MCP 標準協議：支援任何 MCP 相容工具

安裝方式

方式 A：Claude Code Plugin（推薦）

# 1. 前置需求：Ollama + 嵌入模型
ollama serve &
ollama pull nomic-embed-text

# 2. Clone 並建構
git clone https://github.com/rocker027/engram.git
cd engram
npm install && npm run build

# 3. 安裝 Plugin（一鍵完成 MCP + Hooks + Skills）
claude --plugin-dir ./engram

安裝後自動獲得：

• ✅ MCP Server 自動啟動
• ✅ SessionStart 自動 recall 相關記憶
• ✅ Stop 自動提示 store 重要發現
• ✅ 記憶系統使用指南 Skill

方式 B：手動 MCP 註冊（Antigravity / Gemini CLI）

# 1. 安裝依賴和建構
cd engram
npm install
npm run build

# 2. 啟動 Ollama + 拉取嵌入模型
ollama serve &
ollama pull nomic-embed-text

# 3. 註冊至 Antigravity (mcp_config.json)
# 加入以下設定：
# "engram": {
#   "command": "node",
#   "args": ["/path/to/engram/dist/server.js"]
# }

# 4. 重啟 Antigravity

MCP Tools

Tool	功能
memory_store	儲存記憶（自動嵌入 + 分類）
memory_recall	語意+關鍵字混合搜尋
memory_forget	刪除記憶
memory_update	更新記憶內容
memory_stats	記憶庫統計

設定

預設使用 Ollama (nomic-embed-text, 768 維)。可在 ~/.engram/config.json 自訂：

{
  "embedding": {
    "baseURL": "http://localhost:11434/v1",
    "apiKey": "ollama",
    "model": "nomic-embed-text",
    "dimensions": 768
  },
  "storage": {
    "dbPath": "~/.engram/lancedb"
  }
}

架構

src/
├── types.ts          # 共用型別
├── embedder.ts       # Ollama 嵌入 + LRU Cache
├── store.ts          # LanceDB CRUD + 向量/BM25 搜尋
├── retriever.ts      # 8 步混合檢索流水線
├── noise-filter.ts   # Trigram Jaccard 去重
├── decay-engine.ts   # Weibull 衰減引擎

AI 工具整合

安裝完成後，在專案的 GEMINI.md 或 CLAUDE.md 中加入以下規則，讓 AI Agent 自動使用記憶系統。

Antigravity / Gemini CLI（GEMINI.md）

在專案根目錄的 GEMINI.md 中加入：

## 記憶系統協議（Engram）

你擁有**跨對話長期記憶**能力，透過 Engram 的五個工具操作。

### 🔄 對話開始時

- 根據使用者的第一句話，用 `memory_recall` 搜尋相關記憶
- 若有相關記憶，在回答中自然融入（不要逐條列出）

### 💾 對話過程中自動儲存

偵測到以下內容時，**主動**使用 `memory_store` 儲存：

| 分類 | 觸發情境 | 範例 |
|------|---------|------|
| `preference` | 使用者表達偏好 | 「我喜歡用 Riverpod」 |
| `decision` | 技術方案確定 | 「這個專案用 GoRouter」 |
| `fact` | 重要事實、設定 | 「API baseURL 是 /api/v1」 |
| `lesson` | 踩坑經驗、教訓 | 「重構前要先寫測試」 |
| `entity` | 重要的專案/工具/人物 | 「stock-screener 專案」 |

### ⚠️ 規則

1. **防重複**：儲存前先 `memory_recall` 檢查，已存在則用 `memory_update`
2. **不存垃圾**：臨時性問題、一次性指令不要存
3. **scope 分層**：跨專案用 `global`，專案內用 `project:<名稱>`
4. **重要度**：偏好/教訓 0.8+、決策 0.7-0.9、事實 0.5-0.7
5. **隱私**：禁止儲存 API 金鑰、密碼、Token 等敏感資訊

Claude Code（CLAUDE.md）

在專案根目錄的 CLAUDE.md 中加入相同內容即可。Claude Code 會自動讀取 CLAUDE.md 作為系統指令。

安裝檢測

本專案提供安裝檢測 Skill，可自動偵測環境並生成設定：

skills/
└── engram-setup/
    └── SKILL.md    # 7 步驟 SOP：環境檢測 → 設定生成 → MCP 註冊

詳見 skills/engram-setup/SKILL.md。