Metadata-Version: 2.4
Name: timeless-memory-mcp
Version: 0.2.0
Summary: Timeless Memory - 個人記憶與知識圖譜系統（FTS5 + BM25/Jieba + Gemini Vector Search）
Project-URL: Homepage, https://github.com/chenwei/timeless-memory-mcp
Project-URL: Repository, https://github.com/chenwei/timeless-memory-mcp
Project-URL: Issues, https://github.com/chenwei/timeless-memory-mcp/issues
Author: chenwei
License-Expression: MIT
Keywords: ai,fts5,google-chat,knowledge-management,mcp,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: google-api-python-client>=2.0
Requires-Dist: google-auth-oauthlib>=1.0
Requires-Dist: google-auth>=2.0
Requires-Dist: google-genai>=1.0.0
Requires-Dist: jieba>=0.42.1
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rank-bm25>=0.2.2
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: vector-heavy
Requires-Dist: qdrant-client>=1.7.0; extra == 'vector-heavy'
Requires-Dist: torch>=2.0.0; extra == 'vector-heavy'
Requires-Dist: transformers>=4.35.0; extra == 'vector-heavy'
Description-Content-Type: text/markdown

# 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 | ✅ |

## 安裝

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

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

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

## CLI 使用方式

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

```bash
# 搜尋（三種引擎）
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），包含：

```yaml
---
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 個操作）：

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

## 開發

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

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

# 打包發佈
uv build
uv publish
```

## 授權

MIT License
