timeless-memory-mcp 0.2.0

Timeless Memory - 個人記憶與知識圖譜系統（FTS5 + BM25/Jieba + Gemini Vector Search）

Timeless Memory MCP

個人記憶與知識圖譜系統 — 整合 Google Chat 同步、三引擎搜尋（FTS5 + BM25/Jieba + Gemini Vector）、實體關係圖

v0.2.0 新功能

• BM25 快取機制：jieba 分詞結果持久化，搜尋速度提升 5x+
• 時間過濾：--after / --before 參數，以天為單位精確過濾
• Gemini Vector Search：text-embedding + SQLite 儲存 + chunk/overlap 切分
• 三路搜尋 PK：search-pk 一次跑三種引擎，自動記錄交叉分析
• 搜尋日誌：所有搜尋自動記錄 JSONL，供後續優化分析
• Chat Sync 5 步驟：下載 → 轉換 → FTS5 索引 → BM25 快取 → Vector Embedding（全增量）

搜尋引擎

引擎	適用場景	索引方式	時間過濾
fts5	英文/技術術語精確匹配	SQLite FTS5 虛擬表	✅
bm25_jieba	中文搜尋首選，分詞準確	Pickle 快取（9.5s 重建）	✅
vector	語意相似搜尋	Gemini embedding + SQLite	✅

安裝

# 推薦：使用 uvx
uvx timeless-memory-mcp

# 或使用 pip
pip install timeless-memory-mcp

# 或從原始碼
cd timeless-memory-mcp
pip install -e .

CLI 使用方式

本系統主要透過 timeless-cli 命令列工具操作：

# 搜尋（三種引擎）
timeless-cli memory search "教育雲部署" --mode bm25_jieba --limit 10
timeless-cli memory search "deploy error" --mode fts5 --limit 10
timeless-cli memory search "系統不穩定怎麼處理" --mode vector --limit 10

# 時間過濾
timeless-cli memory search "P310" --mode bm25_jieba --after 2026-04-01 --before 2026-04-20

# 三路 PK（推薦）
timeless-cli search-pk "教育雲部署問題" --after 2026-04-01 --limit 5

# Google Chat 同步（5 步驟全增量）
timeless-cli chat sync --overlap-days 1 --workers 5

# 重建索引
timeless-cli rebuild              # FTS5 索引
timeless-cli rebuild-bm25-cache   # BM25 快取
timeless-cli rebuild-vectors      # Vector Embedding（需 GEMINI_API_KEY）

# 實體管理
timeless-cli entity create person "張三" --aliases "san,zhangsan"
timeless-cli entity list --type person
timeless-cli entity read person-張三

# 關聯管理
timeless-cli relation create person-張三 project-教育雲 works_on
timeless-cli relation list person-張三

# 統計
timeless-cli stats

環境變數

變數	用途	必要性
TIMELESS_HOME	資料目錄（預設 ~/Documents/timeless-memory）	選填
GEMINI_API_KEY	Gemini Embedding API（vector 搜尋用）	vector 模式必填
GOOGLE_CHAT_CREDENTIALS	Google Chat OAuth JSON（同步用）	Chat 同步必填

Vector Search 設計

• Embedding 模型：Gemini gemini-embedding-001（768 維）
• Chunk 策略：800 字/chunk，200 字 overlap
• 儲存：SQLite embeddings_v2 表（~3KB/chunk）
• 搜尋：全量載入 numpy → cosine similarity → max pooling per memory
• 增量更新：chat sync 後自動對新記憶做 embedding

資料結構

~/Documents/timeless-memory/
├── .database/
│   └── memories.db          # SQLite（記憶 + FTS5 + 實體 + embeddings_v2）
├── data/
│   └── google-chat/         # 每日對話 Markdown（BM25 掃描來源）
├── sources/
│   └── google-chat/         # 原始 JSON（API 下載備份）
└── logs/
    ├── search-YYYY-MM-DD.jsonl    # 搜尋日誌
    └── search-pk-results.jsonl    # 三路 PK 評比記錄

記憶基礎單元

每筆記憶 = 一個聊天室的一天對話（daily-*.md），包含：

---
id: daily-2026-04-20-xxx
title: "P310_教育雲第二年 - 2026-04-20"
date: "2026-04-20"
space_name: "P310_教育雲第二年_AAQA"
participants: ["10671516", "10083391"]
message_count: 32
tags: [工作對話, P310_教育雲第二年_AAQA]
---
# 對話內容
[2026-04-20 09:15] 10671516: ...

MCP Server 模式

除了 CLI，也支援 MCP Server 模式（7 個統一工具，38 個操作）：

{
  "mcpServers": {
    "timeless-memory": {
      "command": "uvx",
      "args": ["timeless-memory-mcp"],
      "env": {
        "TIMELESS_HOME": "/path/to/timeless-memory",
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

開發

# 本地開發
pip install -e ".[dev]"

# 重新安裝（測試修改）
uv tool install --force --reinstall --from . timeless-memory-mcp

# 打包發佈
uv build
uv publish

授權

MIT License