Memdocs

MemDocs 🧠

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+ Productivity

`

Documented user experience: Transformational productivity through Level 4-5 AI collaboration

📖 Learn More:

- [Quick Start: Blog Post](docs/EMPATHY_MEMDOCS_BLOG_POST.md) - Engaging narrative explaining the five levels

- [Executive Summary](docs/EMPATHY_MEMDOCS_EXECUTIVE_SUMMARY.md) - 1-page overview for teams & investors

- [Technical Deep-Dive](docs/EMPATHY_MEMDOCS_SYNERGY.md) - 21-page analysis with code examples

---

🎯 What is MemDocs?

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.

💡 The Problem

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.

✨ The Solution

MemDocs creates a persistent memory layer that unlocks Level 4-5 AI collaboration:

• 🧠 Remembers your project across sessions (via .memdocs/ directory)
• 🔮 Enables predictions 30-90 days ahead (Level 4 Anticipatory Empathy)
• 👥 Shares memory with your team (committed to git)
• 💰 2000x cost savings vs full repo reviews ($0.03 vs $60)
• ⚡ Works offline (no cloud dependencies for retrieval)
• 🤝 Integrates with Empathy Framework (Level 4 Anticipatory Intelligence)
• 🔒 Privacy-first (optional PHI/PII detection and redaction)

Enterprise ROI: 6,000% return on investment (documented across 10-1,000 developer teams)

---

🚀 Quick Start

Installation

# 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]"

Basic Usage

# 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

Large Repository Workflow

# 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

Your First Documentation

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

---

✨ Key Features

🧠 Git-Native Memory

• All documentation stored in .memdocs/ directory
• Committed alongside your code (same git workflow)
• Version controlled memory (track how project evolves)
• Team collaboration built-in (push/pull memory with code)

🎯 Smart Scoping

• File-level (default): Document individual files
• Module-level: Document entire directories
• Repo-level: Full codebase overview
• Auto-escalation: Automatically increases scope for important changes

🤖 AI-Powered Summarization

• Claude Sonnet 4.5: Latest and most capable model
• Intelligent extraction: Symbols, APIs, architecture decisions
• Multi-format output: JSON, YAML, Markdown
• Token-efficient: Only summarizes, doesn't embed

🔍 Semantic Search (Optional)

• Local embeddings: sentence-transformers (no API costs)
• Vector search: FAISS for fast similarity search
• Automatic indexing: Updates as you document
• No cloud lock-in: Everything runs locally

📈 Enterprise Scale - Large Repository Support

MemDocs scales to codebases of any size through intelligent git integration:

• Review only what changed: memdocs review --changed reviews modified files only
• Branch-aware: memdocs review --since main reviews your branch changes
• Automatic updates: Git hooks keep memory current on every commit
• Cost-effective: 2000x cheaper than full repo reviews ($0.03 vs $60)
• Lightning fast: 15 seconds instead of hours

Perfect 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:

🔌 MCP Server (Model Context Protocol)

• Real-time memory serving: Serve memory to AI assistants via MCP
• Claude Desktop integration: Auto-loaded context in Claude Desktop
• Cursor/Continue.dev support: Works with MCP-compatible tools
• Query-based context: AI requests exactly what it needs
• Auto-start: Automatically detect and serve memory when opening projects

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

🚀 The Complete Stack: Transformational Productivity

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:

Real-world results:

• 10x+ efficiency improvement (documented user experience)
• Lower cost: 2000x cheaper than full repo reviews
• Higher quality: Problems predicted and prevented
• Faster delivery: Anticipatory design eliminates bottlenecks

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-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!

Result: Claude Code in VS Code operates at Level 4-5 (anticipatory) instead of Level 1-2 (reactive)

---

🔗 Empathy Framework Integration: Level 4-5 AI Collaboration

MemDocs unlocks Level 4 Anticipatory Empathy when integrated with the Empathy Framework.

The Five Levels of AI Collaboration:

Why MemDocs is Essential:

• 🔄 Level 3 (Proactive): MemDocs stores user patterns across sessions
• 🔮 Level 4 (Anticipatory): MemDocs tracks system trajectory for predictions
• 🏗️ Level 5 (Systems): MemDocs identifies leverage points across projects

Without persistent memory, AI is stuck at Level 1-2 forever.

📚 Deep Dive Resources:

• [Blog Post](docs/EMPATHY_MEMDOCS_BLOG_POST.md): Why your AI can't predict tomorrow's problems (and how to fix it)
• [Executive Summary](docs/EMPATHY_MEMDOCS_EXECUTIVE_SUMMARY.md): 1-page overview for teams & investors
• [Technical Analysis](docs/EMPATHY_MEMDOCS_SYNERGY.md): 21-page deep-dive comparing five empathy frameworks

Integration features:

• ✅ Works seamlessly with Empathy framework (1.6.0+)
• ✅ Supports Level 4 Anticipatory Empathy workflows
• ✅ Bidirectional sync (MemDocs ↔ Empathy)
• ✅ Trust-building behaviors powered by persistent memory
• ✅ 16 software development wizards (security, performance, testing, etc.)
• ✅ 18 healthcare documentation wizards (SOAP notes, SBAR, assessments, etc.)

🔒 Privacy & Security

• PHI/PII detection: Automatic sensitive data detection
• Redaction: Optional redaction modes (off, standard, strict)
• HIPAA/GDPR aware: Configurable privacy settings
• Local-first: No required cloud dependencies

---

📖 Documentation

Configuration

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 gi