git clone <repository-url>
cd ai-memory-mcp
pip install .

pip install ".[local-embedding]"

pip install ".[dev]"

# ── Storage ──────────────────────────────────────────────
storage:
  sqlite_path: "~/.ai-memory/memory.db"   # SQLite database for core memories
  chroma_path: "~/.ai-memory/chroma"      # ChromaDB directory for vector storage
  wal_mode: true                           # SQLite WAL mode for concurrent reads

# ── L1 Hot Cache ─────────────────────────────────────────
cache:
  max_size: 100            # LRU cache capacity (number of entries)
  ttl_seconds: 3600        # Cache entry TTL (1 hour)

# ── Embedding ────────────────────────────────────────────
embedding:
  api:                                      # Primary: OpenAI API (higher quality)
    enabled: false
    model: "text-embedding-3-small"
    base_url: "https://api.openai.com/v1"
    api_key_env: "OPENAI_API_KEY"           # Reads from environment variable
    dimension: 1536
  local:                                    # Fallback: local model (offline)
    model: "all-MiniLM-L6-v2"
    dimension: 384
    cache_dir: "~/.ai-memory/models"
  hash_fallback:                            # Last resort: hash-based embedding
    dimension: 256

# ── Three-Factor Reinforcement Weights ───────────────────
weights:
  w_retrieval: 0.3              # Call frequency weight (Hebbian)
  w_adoption: 0.4               # Adoption rate weight (Dopamine)
  w_feedback: 0.3               # Feedback score weight (Modulator)
  max_access_count: 100         # Log compression denominator
  feedback_half_life_days: 14   # Feedback decay half-life

# ── Decay ────────────────────────────────────────────────
decay:
  confidence_lambda: 0.03       # Ebbinghaus decay rate (~23-day half-life)
  hebbian_decay: 0.99           # Hebbian connection decay per update
  forget_threshold: 0.1         # Weight below this enters forget queue

# ── Retrieval ────────────────────────────────────────────
retrieval:
  l1_top_k: 5                   # L1 seed node count
  l2_max_expansion: 10          # L2 expansion candidate limit
  l3_max_results: 10            # L3 final result limit
  pagerank:
    damping: 0.5                # Personalized PageRank damping factor
    max_iterations: 3           # PageRank iterations
    min_activation: 0.01        # Stop spreading below this activation
  fusion:
    vector_weight: 0.5          # Dense retrieval weight
    bm25_weight: 0.3            # Sparse retrieval weight
    graph_weight: 0.2           # Graph expansion weight
  dedup_threshold: 0.85         # Similarity above this triggers merge

# ── Token Budget ─────────────────────────────────────────
token:
  default_budget: 2000          # Default token budget for context
  cold_start_budget: 800        # When memory count < 50
  min_budget: 500
  max_budget: 3000

# ── Lifecycle ────────────────────────────────────────────
lifecycle:
  compress_after_days: 7        # Compress episodic memories after N days
  archive_after_days: 30        # Move to archive after N days
  audit_interval_days: 7        # Weekly audit
  decay_interval_hours: 24      # Daily decay

# ── Governance ───────────────────────────────────────────
governance:
  auto_merge_threshold: 0.90    # Auto-merge if similarity above this
  auto_delete_criteria:
    min_access_count: 0
    max_importance: 0.5
    require_negative_feedback: true
  weak_edge_threshold: 0.05     # Prune Hebbian edges below this

# ── MCP Server ───────────────────────────────────────────
mcp:
  server_name: "ai-memory"
  server_version: "0.1.0"

# ── Personal Memory Modules ──────────────────────────────
personal:
  enabled: true
  data_dir: "~/.ai-memory/personal"

~/.ai-memory/
  memory.db              # Core memory SQLite database (WAL mode)
  chroma/                # ChromaDB vector store
  models/                # Cached local embedding model
  config.yaml            # Optional config override
  vault/                 # Encryption vault metadata
    .vault_autokey       # Auto-mode Fernet key (0600 permissions)
  personal/              # Personal memory module data
    habits.db
    experiences.db
    knowledge.db
    lifestyle.db
    accounts.db
    cross_links.db       # Cross-module link graph

{
  "mcpServers": {
    "ai-memory": {
      "command": "ai-memory-mcp",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "ai-memory": {
      "command": "/path/to/venv/bin/ai-memory-mcp",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "ai-memory": {
      "command": "ai-memory-mcp",
      "args": []
    }
  }
}

ai-memory-mcp

git clone <repository-url>
cd ai-memory-mcp
pip install -e ".[dev]"

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run a specific test file
pytest tests/test_core.py

# Generate coverage report
pytest --cov=memory_plugin --cov-report=html
# Open htmlcov/index.html in a browser

python benchmarks/benchmark_retrieval.py    # Retrieval pipeline performance
python benchmarks/benchmark_performance.py  # Overall system performance

ai-memory-mcp/
|-- config.yaml                        # Main configuration file
|-- pyproject.toml                     # Package metadata, dependencies, entry points
|-- src/
|   `-- memory_plugin/
|       |-- __init__.py
|       |-- mcp_server.py              # MCP server: 9 core tool handlers, lifecycle
|       |-- personal_mcp_tools.py      # 15 personal tool definitions + dispatcher
|       |-- config.py                  # Configuration dataclasses, YAML loading
|       |-- models.py                  # MemoryEntry, Feedback, Provenance, SearchResult
|       |-- embedding.py              # Embedding provider (API / local / hash fallback)
|       |-- weights.py                # Three-factor reinforcement weight calculator
|       |-- hebbian.py                # Hebbian connection weight updater
|       |-- governance.py             # Audit, redundancy/contradiction detection, health score
|       |-- lifecycle.py             # Decay, compression, forgetting, archiving
|       |-- bootstrap.py             # Codebase scanner for cold-start memory extraction
|       |-- utils.py                  # Cosine similarity, token counting, tag extraction
|       |-- retrieval/
|       |   |-- __init__.py
|       |   |-- l1_direct.py          # L1: vector + BM25 parallel recall, fusion
|       |   |-- l2_expansion.py       # L2: Personalized PageRank spreading activation
|       |   |-- l3_context.py         # L3: weighted scoring, token-budget packing, formatting
|       |   `-- fusion.py             # Multi-channel score fusion + semantic deduplication
|       |-- storage/
|       |   |-- __init__.py
|       |   |-- sqlite_store.py       # SQLite storage with WAL mode
|       |   |-- vector_store.py       # ChromaDB vector storage
|       |   `-- cache.py              # LRU hot cache with TTL
|       `-- personal/
|           |-- __init__.py
|           |-- manager.py            # PersonalMemoryManager: unified facade, cross-module linking
|           |-- crypto.py             # VaultCrypto: Argon2id + Fernet encryption
|           |-- masking.py            # DataMasking: PII masking utilities
|           |-- password_utils.py     # Password generator + strength evaluator
|           |-- shared_types.py       # PrivacyLevel, ModuleType, LinkType enums
|           |-- account_models.py     # AccountEntry, SecurityQuestion, APIKeyEntry
|           |-- account_store.py      # AccountStore: encrypted CRUD operations
|           |-- habits_models.py      # Habit, HabitCheckIn, frequency/category enums
|           |-- habits_store.py       # HabitStore: check-ins, streaks, overdue detection
|           |-- experiences_models.py # Experience, EmotionPoint, GrowthOutcome, Reflection
|           |-- experiences_store.py  # ExperienceStore: CRUD, search, stats
|           |-- knowledge_models.py   # KnowledgeCard, ReviewRecord, SM-2 types
|           |-- knowledge_store.py    # KnowledgeStore: SM-2 scheduling, decay risk
|           |-- lifestyle_models.py   # Preference, Routine, Contact, Address
|           `-- lifestyle_store.py    # LifestyleStore: multi-entity storage
|-- tests/                             # 558 tests, 96% coverage
|   |-- conftest.py
|   |-- test_core.py
|   |-- test_personal.py
|   |-- test_personal_mcp.py
|   |-- test_auto_crypto.py
|   |-- test_habits.py
|   |-- test_experiences.py
|   |-- test_knowledge.py
|   |-- test_lifestyle.py
|   `-- test_manager.py
|-- benchmarks/                        # Performance benchmarking scripts
|-- data/                              # Runtime data (vault, databases)
`-- coverage.json                      # Coverage report data