carrymem: Instructions file for Claude Code

CLAUDE.md — CarryMem AI 协作指引

本文件为 AI 代理（Claude / Codex 等）在 CarryMem 仓库内工作提供统一上下文。所有命令均假设在仓库根目录执行，且已激活包含 dev extras 的虚拟环境。

---

项目概述

• CarryMem 是一个可移植的 AI 记忆层：让 AI 自动记住用户的偏好、决策与纠正，跨模型 / 工具 / 设备复用，无需每次重复自我介绍。
• 当前版本：0.11.2（来源：src/carrymem/__version__.py，2026-10-02 校准）
• 核心技术栈：
  • Python 3.12+（setup.py 中 python_requires=">=3.12"）
  • SQLite + FTS5（默认存储与全文检索）
  • MCP（Model Context Protocol）服务器集成
  • 核心依赖：PyYAML>=5.0 + cryptography>=50.0.0（v0.11.0 起安全版本下限），语言检测 / 向量检索 / LLM / TUI 均为可选 extras
• 仓库：https://github.com/lulin70/carrymem
• CI 默认分支：new-main（非 main，提交 PR 时注意基分支）

---

安装与构建

# 开发模式安装（含 dev extras：pytest 全家桶、black、flake8、mypy、pre-commit 等）
pip install -e ".[dev]"

# 用户安装（已发布到 PyPI）
pip install carrymem

# 完整功能安装
pip install -e ".[full]"

# 构建 sdist + wheel（CI 使用流程）
python -m build
twine check dist/*

# 全新虚拟环境验证安装（CI 的 build gate）
python -m venv /tmp/carrymem_venv
/tmp/carrymem_venv/bin/pip install $(ls dist/carrymem-*.whl | head -1)
/tmp/carrymem_venv/bin/python -c "import carrymem; print(carrymem.__version__)"

CLI 入口：carrymem（entry_points → carrymem.cli:main），也可 python -m carrymem。

---

测试命令

pytest 配置位于 pyproject.toml 的 [tool.pytest.ini_options]：默认开启 --cov=carrymem、--strict-markers、asyncio_mode = "auto"，覆盖率门槛 fail_under = 75。

# 全量测试（默认带覆盖率，输出 term/html/xml 三份报告）
pytest tests/

# 排除慢测试（CI 主 gate 使用，附加 --timeout=120）
pytest tests/ -m "not slow" -q

# 仅 E2E 测试（tests/e2e/，共 18 个场景文件）
pytest tests/e2e/

# 带覆盖率（默认即开启，显式写法）
pytest tests/ --cov=carrymem --cov-report=term-missing

# 仅单元 / 集成测试（按 marker 过滤）
pytest tests/ -m "unit"
pytest tests/ -m "integration"

# 长超时调试单个文件
pytest tests/test_e2e_mcp_tools.py --timeout=300 -v

可用 marker：slow、integration、unit、asyncio、coverage。

E2E 测试覆盖：并发访问、大数据集、MCP 工具、适配器切换、加密全链路、完整生命周期、用户场景、边界用例、经验精炼、安全管线、版本回滚、用户旅程。发布前务必运行 E2E 套件做模拟真实用户使用的验证。

---

代码质量

CI 的 lint gate（.github/workflows/ci.yml）执行以下命令，本地应保持一致：

# 格式检查（line-length=120，target py312）
black --check --diff --color --line-length=120 src/ tests/
isort --check-only --diff src/ tests/

# Lint（max-line-length=120，配置见 .flake8）
flake8 src/ tests/ --count --max-line-length=120 --statistics

# 类型检查（配置在 pyproject.toml [tool.mypy]）
mypy src/