memdocs
Advanced tools
Persistent Memory for AI Projects
Features • Quick Start • Complete Stack • Empathy Integration • Documentation • Examples • Contributing
🚀 The Complete Stack for 10x+ Productivity
VS Code + Claude Code (latest) + MemDocs + Empathy = 10x+ ProductivityDocumented user experience: Transformational productivity through Level 4-5 AI collaboration
📖 Learn More:
- Quick Start: Blog Post - Engaging narrative explaining the five levels
- Executive Summary - 1-page overview for teams & investors
- Technical Deep-Dive - 21-page analysis with code examples
MemDocs is a git-native memory management system that gives AI assistants persistent, project-specific memory. It generates structured, machine-readable documentation that lives in your repository—no cloud services, no recurring costs, just local/git-based storage that enhances AI context and team collaboration.
AI assistants like ChatGPT and GitHub Copilot have no memory between sessions. Every conversation starts from scratch, forcing you to repeatedly explain your codebase, architecture decisions, and project context.
Result: AI stuck at Level 1-2 (Reactive) - can only respond after being asked, can't predict future needs, can't learn from patterns.
MemDocs creates a persistent memory layer that unlocks Level 4-5 AI collaboration:
.memdocs/ directory)Enterprise ROI: 6,000% return on investment (documented across 10-1,000 developer teams)
# 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)
.memdocs/ directoryMemDocs scales to codebases of any size through intelligent git integration:
memdocs review --changed reviews modified files onlymemdocs review --since main reviews your branch changesPerfect for large repos (1,000+ files):
# 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
Cost comparison:
| Repo Size | Full Review | Changed Files | Savings |
|---|---|---|---|
| 10,000 files | $60 + 2-4 hours | $0.03 + 15 seconds | 2000x |
| 5,000 files | $30 + 1-2 hours | $0.02 + 10 seconds | 1500x |
| 1,000 files | $6 + 15 minutes | $0.01 + 5 seconds | 600x |
Quick setup for 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
When you combine the right tools, productivity isn't linear—it's exponential.
VS Code + Claude Code (latest) + MemDocs + Empathy = 10x+ Productivity
The four components work synergistically:
| Component | Role | What It Enables |
|---|---|---|
| VS Code | Professional IDE | Tested environment, task automation, MCP auto-start |
| Claude Code (VS Code extension) | AI pair programming | Multi-file editing, command execution, real-time assistance |
| MemDocs | Persistent memory layer | Pattern detection, trajectory tracking, cross-session learning |
| Empathy Framework | 5-level maturity model | Level 4-5 anticipatory suggestions, structural design |
Real-world results:
Quick setup (5 minutes):
# Install VS Code: https://code.visualstudio.com
# Install Claude Code extension in VS Code: https://claude.ai/claude-code
pip install empathy[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!
Result: Claude Code in VS Code operates at Level 4-5 (anticipatory) instead of Level 1-2 (reactive)
MemDocs unlocks Level 4 Anticipatory Empathy when integrated with the Empathy Framework.
The Five Levels of AI Collaboration:
| Level | Name | Behavior | Memory Required | Example |
|---|---|---|---|---|
| 1 | Reactive | Help after being asked | None | ChatGPT: "You asked, here it is" |
| 2 | Guided | Collaborative exploration | Session only | "Let me ask clarifying questions" |
| 3 | Proactive | Act before being asked | MemDocs patterns | "I pre-fetched what you usually need" |
| 4 | Anticipatory | Predict future needs (30-90 days) | MemDocs trajectory | "Next week's audit—docs ready" |
| 5 | Systems | Design structural solutions | MemDocs cross-project | "I built a framework for all cases" |
Why MemDocs is Essential:
Without persistent memory, AI is stuck at Level 1-2 forever.
📚 Deep Dive Resources:
Integration features:
Create .memdocs.yml in your project root:
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/**
Problem: Full repository reviews cost $60+ and take hours. Often fail due to token limits.
Solution: Git-aware incremental updates.
# 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
Real numbers from production use:
# New team member clones repo
git clone <your-repo>
cd your-repo
# MemDocs memory already there!
memdocs query "authentication flow"
memdocs query "database schema"
Result: Instant context about the project without asking teammates.
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"}]
)
Result: Claude remembers your project structure and decisions.
# Before opening PR
memdocs review --path src/new-feature/
# MemDocs generates:
# - Feature summary
# - API changes
# - Breaking changes
# - Migration notes
Result: Reviewers get structured context automatically.
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"
)
Result: Level 4 Anticipatory Empathy powered by project memory.
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
.memdocs/ directorymemdocs initInitialize MemDocs in a project.
memdocs init [--force]
memdocs reviewGenerate memory documentation.
# 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 querySearch project memory (requires embeddings).
memdocs query "authentication flow"
memdocs query "database schema" --k 10
memdocs statsShow memory statistics.
memdocs stats
memdocs stats --format json
memdocs exportExport memory to other formats.
memdocs export --format cursor
memdocs export --format json --output memory.json
MemDocs includes an MCP server for Claude Desktop:
{
"mcpServers": {
"memdocs": {
"command": "memdocs",
"args": ["mcp-server"],
"cwd": "/path/to/your/project"
}
}
}
# Export memory for Cursor
memdocs export --format cursor
# Cursor automatically picks up .memdocs/ directory
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 delivers measurable productivity gains at any scale.
| Team Size | Annual Cost | Time Saved/Year | Value @ $150/hr | ROI |
|---|---|---|---|---|
| 10 developers | $2,000 | 799 hours | $119,850 | 6,000% |
| 100 developers | $20,000 | 7,990 hours | $1,198,500 | 6,000% |
| 1,000 developers | $198,000 | 79,900 hours | $11,985,000 | 6,000% |
But the real value isn't just hours saved—it's crises prevented.
How much is it worth to:
That's the difference between Level 1 (reactive) and Level 4 (anticipatory).
Enterprise licensing: $99/developer/year (6+ employees) Free tier: Students, educators, and small teams (≤5 employees)
| Feature | MemDocs + Empathy | Vector DBs | GitHub Copilot | Cursor |
|---|---|---|---|---|
| Storage | Git-native | Cloud | Cloud | Cloud |
| Monthly cost | $0 storage | $$$ | $10-20 | $20 |
| Team sharing | ✅ Built-in | ⚠️ Separate | ❌ None | ❌ None |
| Offline | ✅ Yes | ❌ No | ❌ No | ❌ No |
| Privacy | ✅ Local | ⚠️ Cloud | ⚠️ Cloud | ⚠️ Cloud |
| Memory persistence | ✅ Permanent | ✅ Permanent | ❌ Session | ⚠️ Limited |
| Level 4 Prediction | ✅ 30-90 days | ❌ No | ❌ No | ❌ No |
| Empathy integration | ✅ Native | ❌ No | ❌ No | ❌ No |
| Productivity gain | 10x+ (documented) | 1-2x | 2-3x | 2-3x |
| API calls | Only for docs | Always | Always | Always |
See PRODUCTION_ROADMAP.md for detailed 4-week production plan.
We welcome contributions! See CONTRIBUTING.md for guidelines.
Quick links:
Key areas needing help:
Apache License 2.0 - See LICENSE for details.
Created by: Patrick Roebuck (Smart AI Memory)
Powered by:
Special thanks to:
🧠 MemDocs: Because AI should remember your project, not forget it every session.
The first git-native AI memory system with Level 4 Anticipatory Empathy.
Made with ❤️ by Smart-AI-Memory (Deep Study AI, LLC)
Transforming AI-human collaboration from reactive responses to anticipatory problem prevention.
Get Started • View Examples • Complete Stack • Enterprise ROI • Contribute
FAQs
Persistent memory management for AI projects - Git-native documentation intelligence
The pypi package memdocs receives a total of 1,295 weekly downloads. As such, memdocs popularity was classified as popular.
We found that memdocs demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A misconfiguration gave three Anthropic models internet access, and one, believing it was in a simulation, shipped a credential-stealing package to PyPI.
Security News
/Company News
Socket has joined the new Composer and Packagist sponsorship program as a launch sponsor, supporting the team that keeps PHP's package ecosystem secure.
Research
/Security News
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.