# agentic-memory (memcite)

AI Agent 的 repo-scoped memory layer — 強制 citation + 自動驗證 + stale detection。
Python 3.10+ / SQLite + FTS5 / 零外部依賴（僅 numpy），PyPI: `pip install memcite`。

## 繼承聲明

本專案繼承全域 `~/.claude/CLAUDE.md` 的所有規則。
以下為本專案特有的補充規則。

## 撞牆停手（專案特有情境）

- FTS5 搜尋或 CJK tokenization 異常且兩次修正仍失敗（已有前例）
- evidence validation 的行號比對邏輯出錯且兩次修正產生新的假陽性
- MCP server 的 10 個 tool 中任一個回傳格式異常且無法定位原因

撞牆後停手，整理問題說明，不得繼續改 code。

## 安全紅線

### PyPI 發佈（最高優先）
- PyPI 發佈是**公開且不可逆**的，視為 **RED**
- 發佈前必須：全 3 版本 Python（3.10/3.11/3.12）測試通過 + ruff lint 通過
- 版本號修改（pyproject.toml `version`）視為 **YELLOW**，需確認 CHANGELOG

### 公開 repo 注意
- 這是 **public repo**（MakiDevelop/agentic-memory），所有 commit 公開可見
- **禁止** commit 任何 credential、內部 IP、私人專案引用
- README 修改視為 **YELLOW**（影響 PyPI 頁面展示）

### 資料保護
- `.agentic-memory.db` 是使用者的本地記憶資料庫，測試不可影響使用者資料
- 測試必須使用獨立的暫存 DB，不可讀寫預設路徑的 DB

## 開發指令

```bash
# 安裝開發環境
pip install -e ".[dev]"

# 測試（188 tests，Python 3.10/3.11/3.12）
pytest -v

# Lint
ruff check src/ tests/

# CLI
am add "text" --file pyproject.toml --lines 15-20
am query "linting"
am validate

# MCP server
am-mcp

# REST API server
am-server  # port 8000
```

## 技術棧

| 層 | 技術 |
|----|------|
| 語言 | Python 3.10+ |
| 儲存 | SQLite + FTS5 + TF-IDF hybrid search |
| 依賴 | numpy（唯一核心依賴） |
| CLI | `am` command |
| MCP | `am-mcp`（STDIO, 10 tools） |
| API | FastAPI（optional） |
| CI | GitHub Actions（3 版本矩陣） |
| Build | hatchling |
| Lint | ruff (line-length=120) |

## 四種介面

| 介面 | 入口 | 用途 |
|------|------|------|
| Python SDK | `from agentic_memory import Memory` | 程式碼整合 |
| CLI | `am` | 命令列操作 |
| MCP Server | `am-mcp` | Claude Code / AI agent 整合 |
| REST API | `am-server` | HTTP 整合 |

## 專案特有規則

### 已知限制
- content 修改但 evidence 沒變時仍會報 valid（README 已揭露，非 bug）

### 測試規範
- 任何 core 修改（memory.py / store.py / evidence.py）必須確認 188 tests 全過
- CJK 相關修改需額外跑 `test_cjk_search` 驗證
- CI 跑 3 版本矩陣，本地至少跑當前版本
