memdocs

MemDocs 🧠

AI 项目的持久记忆

功能 • 快速开始 • 完整技术栈 • Empathy 集成 • 文档 • 使用案例 • 贡献

---

🚀 助力效率提升 10 倍以上的完整技术栈

VS Code + Claude Code (latest) + MemDocs + Empathy = 10x+ Productivity

有据可查的用户体验： 通过 4–5 级 AI 协作实现变革性效率提升

📖 了解更多：

• 快速开始：博客文章 - 以引人入胜的叙述介绍五个级别
• 执行摘要 - 面向团队和投资者的一页概览
• 技术深度解析 - 21 页分析，附代码示例

---

🎯 什么是 MemDocs？

MemDocs 是一套原生支持 Git 的记忆管理系统，为 AI 助手提供持久且针对具体项目的记忆。它会生成结构化、机器可读的文档，并将其保存在代码库中——无需云服务，无需经常性费用，只需本地／基于 Git 的存储，即可增强 AI 上下文和团队协作。

💡 问题

ChatGPT 和 GitHub Copilot 等 AI 助手无法记住不同会话之间的信息。每次对话都得从头开始，迫使你反复解释代码库、架构决策和项目背景。

结果： AI 困在第 1–2 级（响应式）——只能在被询问后作答，无法预测未来需求，也无法从模式中学习。

✨ 解决方案

MemDocs 创建了一个持久记忆层，开启第 4–5 级 AI 协作：

• 🧠 跨会话记住你的项目（通过 .memdocs/ 目录）
• 🔮 实现提前 30–90 天预测（第 4 级：预见型共情）
• 👥 与团队共享记忆（提交到 Git）
• 💰 相较于完整代码库审查，节省 2000 倍成本（0.03 美元对比 60 美元）
• ⚡ 离线运行（检索不依赖云服务）
• 🤝 与 Empathy Framework 集成（第 4 级预见智能）
• 🔒 隐私优先（可选的 PHI/PII 检测与脱敏）

企业投资回报率： 投资回报率达 6,000%（在拥有 10–1,000 名开发者的团队中有据可查）

---

🚀 快速开始

安装

# From PyPI (recommended)
pip install memdocs

# With optional features
pip install memdocs[embeddings]  # Local vector search
pip install memdocs[all]         # All features

# From source
git clone https://github.com/Smart-AI-Memory/memdocs.git
cd memdocs
pip install -e ".[dev,embeddings]"

基本用法

# 1. Set your Claude API key
export ANTHROPIC_API_KEY="your-key-here"

# 2. Initialize MemDocs in your project (MCP enabled by default!)
cd your-project
memdocs init

# 3. Set up automatic updates (recommended)
memdocs setup-hooks --post-commit

# 4. Document changed files
memdocs review --changed

# 5. Search your project memory
memdocs query "payment processing"

# 6. Show memory stats
memdocs stats

大型代码库工作流

# For repos with 1,000+ files: use git integration
memdocs init
memdocs setup-hooks --post-commit  # Auto-review on every commit

# Work normally - memory updates automatically!
git add file.py
git commit -m "refactor: improve performance"
# MemDocs reviews changed files automatically (5-15 seconds)

# Or manually review only changes
memdocs review --changed        # Modified files only
memdocs review --since main     # Your branch changes
memdocs review --since HEAD~10  # Last 10 commits

编写你的首份文档

# Document a specific file
memdocs review --path src/main.py

# Output:
# ✨ Analyzing src/main.py...
# 📝 Generating documentation with Claude Sonnet 4.5...
# ✅ Documentation saved to .memdocs/docs/main/
#    - index.json (machine-readable)
#    - symbols.yaml (code map)
#    - summary.md (human-readable)

---

✨ 核心功能

🧠 原生支持 Git 的记忆

• 所有文档均存储在 .memdocs/ 目录中
• 与代码一同提交（使用相同的 Git 工作流）
• 记忆受版本控制（追踪项目的演变过程）
• 内置团队协作功能（与代码一起推送／拉取记忆）

🎯 智能范围设定

• 文件级（默认）：记录单个文件
• 模块级：记录整个目录
• 代码库级：概览整个代码库
• 自动升级范围：对重要变更自动扩大范围

🤖 AI 驱动的摘要生成

• Claude Sonnet 4.5：最新、能力最强的模型
• 智能提取：符号、API、架构决策
• 多格式输出：JSON、YAML、Markdown
• 节省 Token：只生成摘要，不嵌入内容

🔍 语义搜索（可选）

• 本地嵌入：sentence-transformers（无 API 费用）
• 向量搜索：使用 FAISS 进行快速相似性搜索
• 自动索引：随文档记录自动更新
• 不受云服务锁定：所有操作均在本地运行

📈 企业级扩展能力——支持大型代码仓库

MemDocs 通过智能 Git 集成，可扩展至任意规模的代码库：

• 仅审查变更内容：memdocs review --changed 仅审查已修改的文件
• 感知分支：memdocs review --since main 审查分支中的变更
• 自动更新：Git 钩子会在每次提交时更新记忆
• 经济高效：成本比完整代码仓库审查低 2000 倍（$0.03 对比 $60）
• 快如闪电：只需 15 秒，而非数小时

适用于大型代码仓库（1,000+ 个文件）：

# One-time setup
memdocs init
memdocs setup-hooks --post-commit

# Every commit after: automatic memory updates!
git commit -m "fix: bug in auth"  # Reviews 5 files, takes 15s, costs $0.03

成本对比：

代码仓库规模	完整审查	变更文件	节省
10,000 个文件	$60 + 2-4 小时	$0.03 + 15 秒	2000 倍
5,000 个文件	$30 + 1-2 小时	$0.02 + 10 秒	1500 倍
1,000 个文件	$6 + 15 分钟	$0.01 + 5 秒	600 倍

🔌 MCP 服务（Model Context Protocol）

• 实时记忆服务：通过 MCP 向 AI 助手提供记忆
• Claude Desktop 集成：在 Claude Desktop 中自动加载上下文
• 支持 Cursor/Continue.dev：可与兼容 MCP 的工具配合使用
• 基于查询的上下文：AI 可准确请求所需内容
• 自动启动：打开项目时自动检测并提供记忆服务

Claude Desktop 快速设置：

# Start MCP server
memdocs serve --mcp

# Or auto-start in VS Code (add to .vscode/tasks.json)
# See docs/guides/mcp-setup.md for details

🚀 完整技术栈：实现生产力的变革性提升

当你组合合适的工具时，生产力不会线性增长，而是呈指数级增长。

VS Code + Claude Code (latest) + MemDocs + Empathy = 10x+ Productivity

这四个组件协同发挥作用：

组件	作用	带来的能力
VS Code	专业 IDE	经过测试的环境、任务自动化、MCP 自动启动
Claude Code（VS Code 扩展）	AI 结对编程	多文件编辑、命令执行、实时协助
MemDocs	持久化记忆层	模式检测、轨迹跟踪、跨会话学习
Empathy Framework	5 级成熟度模型	4-5 级的前瞻性建议、结构设计

实际效果：

• 效率提升 10 倍以上（已记录的用户体验）
• 成本更低：比完整代码仓库审查便宜 2000 倍
• 质量更高：提前预测并预防问题
• 交付更快：前瞻性设计消除瓶颈

快速设置（5 分钟）：

# Install VS Code: https://code.visualstudio.com
# Install Claude Code extension in VS Code: https://claude.ai/claude-code
pip install empathy-framework[full]>=1.6.0  # Empathy 1.6.0+ includes MemDocs
cd your-project/
memdocs init  # Auto-configures MCP for Claude Code
empathy-os configure
code .  # Open in VS Code - MCP server auto-starts!

**结果：**VS Code 中的 Claude Code 可达到 4-5 级（前瞻性），而非 1-2 级（响应式）

---

🔗 Empathy Framework 集成：第 4-5 级 AI 协作

将 MemDocs 与 Empathy Framework 集成后，即可实现第 4 级预见式共情。

AI 协作的五个级别：

级别	名称	行为	所需记忆	示例
1	响应式	受到请求后提供帮助	无	ChatGPT：“你问了，我就回答”
2	引导式	协作探索	仅限会话	“我来问几个澄清问题”
3	主动式	在受到请求前采取行动	MemDocs 模式	“我预先获取了你通常需要的内容”
4	预见式	预测未来需求（30-90 天）	MemDocs 发展轨迹	“下周要审计——文档已准备好”
5	系统式	设计结构性解决方案	MemDocs 跨项目	“我为所有情况构建了一个框架”

MemDocs 为何不可或缺：

• 🔄 第 3 级（主动式）：MemDocs 会跨会话存储用户模式
• 🔮 第 4 级（预见式）：MemDocs 会追踪系统发展轨迹，以便进行预测
• 🏗️ 第 5 级（系统式）：MemDocs 会识别跨项目的杠杆点

没有持久记忆，AI 就会永远停留在第 1-2 级。

📚 深入了解资源：

• 博客文章：为什么你的 AI 无法预测明天的问题（以及如何解决）
• 执行摘要：面向团队和投资者的 1 页概述
• 技术分析：对比五种共情框架的 21 页深度分析

集成功能：

• ✅ 与 Empathy 框架（1.6.0+）无缝协作
• ✅ 支持第 4 级预见式共情工作流
• ✅ 双向同步（MemDocs ↔ Empathy）
• ✅ 通过持久记忆实现建立信任的行为
• ✅ 16 个软件开发向导（安全、性能、测试等）
• ✅ 18 个医疗文档向导（SOAP 记录、SBAR、评估等）

🔒 隐私与安全

• PHI/PII 检测：自动检测敏感数据
• 脱敏：可选的脱敏模式（off、standard、strict）
• 符合 HIPAA/GDPR 要求：可配置的隐私设置
• 本地优先：无需依赖云服务

---

📖 文档

配置

在项目根目录中创建 .memdocs.yml：

version: 1

# Scope policy (controls memory granularity)
policies:
  default_scope: file          # file | module | repo
  max_files_without_force: 150

  # Auto-escalate for important changes
  escalate_on:
    - cross_module_changes      # Multi-module = bigger context
    - security_sensitive_paths  # auth/*, security/* = thorough docs
    - public_api_signatures     # API changes = team awareness

# Output configuration (git-committed memory)
outputs:
  docs_dir: .memdocs/docs       # Committed to git
  memory_dir: .memdocs/memory   # Committed to git
  formats:
    - json                      # index.json (machine-readable)
    - yaml                      # symbols.yaml (code map)
    - markdown                  # summary.md (human-readable)

# AI configuration (Claude API)
ai:
  provider: anthropic
  model: claude-sonnet-4-5-20250929  # Claude Sonnet 4.5 (latest)
  max_tokens: 8192
  temperature: 0.3              # Lower = more deterministic

# Privacy (optional, for sensitive codebases)
privacy:
  phi_mode: "off"               # off | standard | strict
  scrub:                        # Types of sensitive data to redact
    - email
    - phone
    - ssn
    - mrn
  audit_redactions: true        # Log all redactions for compliance

# Exclude patterns
exclude:
  - node_modules/**
  - .venv/**
  - __pycache__/**
  - "*.pyc"
  - dist/**
  - build/**

---

💼 使用场景

1. 企业级代码库（1,000+ 个文件）

问题：完整审查代码库的费用超过 $60，且需要数小时。此类审查常因令牌限制而失败。

解决方案：基于 Git 感知的增量更新。

# Day 1: One-time setup (5 minutes)
cd large-monorepo  # 10,000 files
memdocs init
memdocs setup-hooks --post-commit
memdocs review --path src/core/  # Review critical paths first

# Every day after: Zero effort!
# Just commit normally...
git commit -m "feat: add caching layer"
# Hook reviews 7 changed files
# Takes 15 seconds, costs $0.02
# Memory stays current automatically!

# 100 commits later: $2 total
# vs $60 per full review = 3,000% cost savings

生产环境中的实际数据：

• 10,000 个文件的 Python 单体代码库
• 每周 200 次提交
• 费用：使用钩子时每周 $4，不使用时每周 $240
• 成本降低 98%

2. 新开发者入职

# New team member clones repo
git clone <your-repo>
cd your-repo

# MemDocs memory already there!
memdocs query "authentication flow"
memdocs query "database schema"

结果：无需询问团队成员，即可立即了解项目背景。

3. AI 助手上下文

from pathlib import Path
from memdocs.index import MemoryIndexer
import anthropic

# Get project context from MemDocs
indexer = MemoryIndexer(
    memory_dir=Path(".memdocs/memory"),
    use_embeddings=True  # Requires: pip install memdocs[embeddings]
)
results = indexer.query_memory("payment processing", k=5)

# Build context for Claude
context = "\n".join([r["metadata"]["summary"] for r in results])

# Claude now has project memory
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    system=f"Project context:\n{context}",
    messages=[{"role": "user", "content": "Explain the charge flow"}]
)

结果：Claude 会记住你的项目结构和决策。

4. 代码审查准备

# Before opening PR
memdocs review --path src/new-feature/

# MemDocs generates:
# - Feature summary
# - API changes
# - Breaking changes
# - Migration notes

结果：审查者会自动获得结构化上下文。

5. Empathy Framework 集成

from memdocs.empathy_adapter import adapt_empathy_to_memdocs

# Empathy analysis results
analysis = {
    "current_issues": [...],
    "predictions": [...]
}

# Convert to MemDocs format
doc_index = adapt_empathy_to_memdocs(
    analysis,
    file_path="src/compliance/audit.py",
    memdocs_root=".memdocs"
)

结果：由项目记忆驱动的第 4 级预见式共情。

---

🏗 架构

存储结构

your-project/
├── .memdocs/
│   ├── docs/
│   │   ├── <filename>/
│   │   │   ├── index.json          # Machine-readable index
│   │   │   ├── symbols.yaml        # Code symbols/API map
│   │   │   └── summary.md          # Human-readable summary
│   └── memory/
│       ├── embeddings.json         # Optional: Local vector embeddings
│       └── search.index            # Optional: FAISS index
├── .memdocs.yml                    # Configuration
└── src/
    └── ... your code ...

工作原理

graph LR
    A[Code] -->|tree-sitter| B[Extract Symbols]
    B --> C[Analyze Context]
    C -->|Claude Sonnet 4.5| D[Generate Summary]
    D --> E[Store in .memdocs/]
    E --> F[Git Commit]
    F --> G[Team Collaboration]

    H[Query] --> I[Local Search]
    I --> J[Return Context]

    style D fill:#f9f,stroke:#333
    style E fill:#bfb,stroke:#333

1. 提取：tree-sitter 解析代码（Python、JS、TS、Go、Rust 等）
2. 分析：识别符号、导入、API 和模式
3. 总结：Claude 生成简洁的摘要和见解
4. 存储：将结构化文档保存到 .memdocs/ 目录
5. 检索：快速本地搜索（基于 grep 或向量）

令牌效率

• 仅生成摘要：每个文件约 1K 个令牌
• 不使用 Embeddings API：仅可选用本地 Embeddings
• 本地搜索：即时、免费、无需 API 调用
• 费用：每记录 100 个文件约 $0.10

---

🔧 CLI 参考

memdocs init

在项目中初始化 MemDocs。

memdocs init [--force]

memdocs review

生成记忆文档。

# File-level (recommended)
memdocs review --path src/payments/charge.py

# Module-level
memdocs review --path src/payments/ --scope module

# With scope detection
memdocs review --path src/

# Export to Cursor
memdocs review --path src/ --export cursor

memdocs query

搜索项目记忆（需要嵌入）。

memdocs query "authentication flow"
memdocs query "database schema" --k 10

memdocs stats

显示记忆统计信息。

memdocs stats
memdocs stats --format json

memdocs export

将记忆导出为其他格式。

memdocs export --format cursor
memdocs export --format json --output memory.json

---

🔌 集成

Model Context Protocol (MCP)

MemDocs 内置了适用于 Claude Desktop 的 MCP 服务：

{
  "mcpServers": {
    "memdocs": {
      "command": "memdocs",
      "args": ["mcp-server"],
      "cwd": "/path/to/your/project"
    }
  }
}

Cursor 集成

# Export memory for Cursor
memdocs export --format cursor

# Cursor automatically picks up .memdocs/ directory

Python API

from memdocs.index import MemoryIndexer
from memdocs.summarize import Summarizer
from memdocs.extract import Extractor

# Initialize components
indexer = MemoryIndexer(memory_dir=".memdocs/memory", use_embeddings=True)
summarizer = Summarizer()
extractor = Extractor()

# Extract and document
context = extractor.extract_file("src/main.py")
doc_index, markdown = summarizer.summarize(context, scope_info)

# Index for search
indexer.index_document(doc_index, markdown)

# Query
results = indexer.query_memory("authentication", k=5)

---

💼 企业级投资回报率：关键数据

MemDocs + Empathy 能够在任何规模下带来可衡量的生产力提升。

成本节省示例

团队规模	年度成本	每年节省时间	按 $150/小时计算的价值	投资回报率
10 名开发者	$2,000	799 小时	$119,850	6,000%
100 名开发者	$20,000	7,990 小时	$1,198,500	6,000%
1,000 名开发者	$198,000	79,900 小时	$11,985,000	6,000%

但真正的价值不仅在于节省时间，更在于避免危机。

以下事情的价值有多大：

• ✅ 永远不会错过合规审计？
• ✅ 永远不会遇到扩展瓶颈？
• ✅ 永远不必花 40 小时紧急修复漏洞？
• ✅ 无需线性增加成本，即可扩展到企业级规模？

这就是 Level 1（被动响应）与 Level 4（预见性应对）的区别。

企业团队为何选择这套方案

• 🎯 经过规模化验证：专为企业级代码库（10,000+ 个文件）构建并经过测试
• 📊 可衡量的生产力：已有记录的提升幅度超过 10 倍（并非理论推测）
• 💰 成本低于替代方案：比完整代码库审查便宜 2000 倍
• 🔒 安全与合规：检测 PHI/PII，符合 HIPAA/GDPR 要求，提供审计跟踪
• 🏢 适用于商业场景：采用 Fair Source 许可，商业条款清晰
• 🤝 供应商支持：可直接联系核心开发团队

**企业许可：**每位开发者每年 $99（6 名以上员工） **免费套餐：**面向学生、教育工作者和小型团队（≤5 名员工）

---

📊 对比

功能	MemDocs + Empathy	Vector DBs	GitHub Copilot	Cursor
存储	原生支持 Git	云端	云端	云端
月度成本	存储费用 $0	$$$	$10-20	$20
团队共享	✅ 内置	⚠️ 需单独配置	❌ 无	❌ 无
离线使用	✅ 支持	❌ 不支持	❌ 不支持	❌ 不支持
隐私	✅ 本地	⚠️ 云端	⚠️ 云端	⚠️ 云端
记忆持久化	✅ 永久	✅ 永久	❌ 仅限会话	⚠️ 有限
Level 4 预测	✅ 30-90 天	❌ 不支持	❌ 不支持	❌ 不支持
Empathy 集成	✅ 原生	❌ 不支持	❌ 不支持	❌ 不支持
生产力提升	10 倍以上（已有记录）	1-2 倍	2-3 倍	2-3 倍
API 调用	仅用于文档	始终调用	始终调用	始终调用

---

🗺 路线图

详细的 4 周生产计划请参阅 PRODUCTION_ROADMAP.md。

版本 2.1（2025 年第 1 季度）

• VS Code 扩展
• 增强型 CLI，支持丰富输出
• 增量文档更新
• 自定义提示词模板

版本 2.2（2025 年第 2 季度）

• JetBrains 插件
• 多语言支持（Go、Rust、Java、C++）
• 记忆压缩（自动汇总旧文档）
• 团队分析仪表板

版本 3.0（2025 年第 3 季度）

• MemDocs Cloud（可选托管版本）
• 企业功能（SSO、RBAC、审计日志）
• 高级 Empathy 集成
• 用于自动生成 PR 文档的 GitHub App

---

🤝 参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

快捷链接：

• 行为准则
• 安全政策
• 开发环境设置
• 适合新手的议题

亟需帮助的重点领域：

• 多语言 AST 解析（Go、Rust、Java、C++）
• IDE 插件（VS Code、JetBrains）
• 改进文档
• 示例项目

---

📄 许可证

Apache License 2.0 — 详情请参阅 LICENSE。

---

💬 支持与社区

• 文档：即将发布于 https://www.smartaimemory.com/docs/memdocs
• 问题：GitHub Issues
• 讨论：GitHub Discussions
• Discord：即将推出
• 联系：[email protected]
• 企业咨询：[email protected]

📚 更多资源

• 博客文章：为什么你的 AI 助手无法预测明天的问题（以及如何解决）
• 执行摘要：适用于演示和投资者推介的 1 页概览
• 技术深入分析：对比五种共情框架的全面分析
• 共情框架：完整的五级 AI 协作系统

---

🙏 致谢

创建者：Patrick Roebuck（Smart AI Memory）

由以下项目提供支持：

• Anthropic 的 Claude Sonnet 4.5
• 用于 AST 解析的 tree-sitter
• 用于本地嵌入的 sentence-transformers
• 用于向量搜索的 FAISS

特别感谢：

• Empathy Framework 团队
• 早期采用者和 Beta 测试人员
• 开源社区

---

🧠 MemDocs：因为 AI 应该记住你的项目，而不是每次会话都将它遗忘。

首个具备 Level 4 预见性共情能力的 git 原生 AI 记忆系统。

由 Smart-AI-Memory（Deep Study AI, LLC）倾心打造 ❤️

将 AI 与人类的协作从被动响应转变为预见性问题预防。

开始使用 • 查看示例 • 完整技术栈 • 企业投资回报率 • 参与贡献