{"id":"851339c7-e9b4-470e-abdb-3bcf14d95827","slug":"mcp-memory-suite","kind":"mcp","name":"mcp-memory-suite","summary":"Comprehensive MCP memory plugin — AI coding memory, personal life memory (habits, experiences, knowledge, accounts), scheduled review, and cross-module linking","owner":"sscctv","repoUrl":"https://github.com/sscctv/mcp-memory-suite","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-12T12:48:46.000Z","addedAt":"2026-10-21T04:57:53.570Z","logoUrl":"https://avatars.githubusercontent.com/u/33175120?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge","databases","developer-tools"],"tags":["ai-agents","ai-memory","claude-code","habit-tracking","knowledge-management","local-first","memory-plugin","persistent-memory"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T02:53:03.363Z","sample":false,"url":"https://conduits.dev/tools/mcp-memory-suite","language":"Python","transports":["stdio"],"install":{"pypi":"mcp-memory-suite"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# MCP Memory Suite\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Tests: 1204](https://img.shields.io/badge/tests-1204-brightgreen.svg)](#development)\n[![Coverage: 91%](https://img.shields.io/badge/coverage-91%25-brightgreen.svg)](#development)\n\nA comprehensive memory plugin for AI coding assistants and personal knowledge management, built on the **Model Context Protocol (MCP)**. It gives AI assistants (Cursor, Claude, and any MCP-compatible client) persistent, intelligent memory that grows smarter with use -- combining neuroscience-inspired retrieval, Hebbian learning, and governance with a full suite of personal data management modules including habits, experiences, knowledge, accounts, and lifestyle tracking.\n\nThe system is organized into two major subsystems:\n\n1. **Core AI Memory System** -- 9 MCP tools for storing, searching, and governing memories that help AI coding assistants recall project context across sessions. Uses a three-layer retrieval pipeline (L1 vector + BM25, L2 PageRank spreading activation, L3 context packing), three-factor reinforcement weights (retrieval frequency, adoption rate, feedback), Hebbian learning, Ebbinghaus decay, and automated codebase bootstrap scanning.\n\n2. **Personal Memory Modules** -- 15 MCP tools for managing personal data: encrypted account vault, habit tracking with streaks, experience recording with emotion journeys, knowledge management with SM-2 spaced repetition, lifestyle information with PII masking, and a unified cross-module manager.\n\n---\n\n## Table of Contents\n\n- [Features Overview](#features-overview)\n  - [Core AI Memory System](#core-ai-memory-system)\n  - [Personal Memory Modules](#personal-memory-modules)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage -- MCP Server Setup](#usage--mcp-server-setup)\n- [MCP Tools Reference](#mcp-tools-reference)\n  - [Core Memory Tools (9)](#core-memory-tools-9)\n  - [Personal Memory Tools (15)](#personal-memory-tools-15)\n- [Security](#security)\n- [Development](#development)\n- [Project Structure](#project-structure)\n- [License](#license)\n\n---\n\n## Features Overview\n\n### Core AI Memory System\n\nThe core system provides long-term, structured memory for AI coding assistants. Instead of storing raw dialogue, it extracts concise facts (30--50 tokens) with rich metadata that drive intelligent retrieval and lifecycle management.\n\n| Feature | Description |\n|---|---|\n| **Three-Layer Retrieval Pipeline** | L1: parallel vector (ChromaDB) + BM25 recall with fusion scoring. L2: Personalized PageRank spreading activation across the Hebbian connection graph. L3: three-factor weighted scoring with Ebbinghaus temporal decay and token-budget packing. |\n| **Three-Factor Reinforcement Weights** | `W = 1 + w_retrieval * f_retrieval + w_adoption * adoption_rate + w_feedback * f_feedback`. Retrieval frequency (Hebbian), adoption rate (dopamine), and time-decayed feedback (neuromodulator) combine to amplify or attenuate each memory's influence. |\n| **Hebbian Learning** | Memories that are co-activated during retrieval have their connection weights strengthened. Connections decay passively over time; weak edges below a threshold are pruned. |\n| **Memory Lifecycle** | Episodic memories are compressed into semantic summaries after a configurable period. Low-weight memories enter a forget queue. Old memories are archived to cold storage. |\n| **Governance Engine** | Automated audits detect redundant memories (high embedding similarity), contradictory memories (conflicting keyword pairs), and weak graph edges. A composite health score (0--100) summarizes store quality across five dimensions. |\n| **Codebase Bootstrap** | On first project connection, a scanner extracts initial memories from config files (tech stack, build tools, directory structure, entry points) to provide immediate value before conversational memories accumulate. |\n| **Write-Time Deduplication** | When a new memory's cosine similarity to an existing one exceeds the threshold, they are automatically merged (content concatenated, tags unioned, importance maximized, access count incremented). |\n| **LRU Hot Cache** | An L1 hot cache with configurable TTL sits in front of the retrieval pipeline for frequently accessed memories. |\n| **Project Isolation** | Memories are scoped by `project_id`, enabling multi-project workflows without cross-contamination. |\n\n### Personal Memory Modules\n\nSix interconnected modules for personal data management, each with its own SQLite store and privacy controls:\n\n| Module | Description |\n|---|---|\n| **Account Vault** | Encrypted credential storage with Argon2id key derivation and Fernet (AES-128-CBC + HMAC-SHA256) encryption. Supports 11 account categories, password history, security questions, API keys, recovery codes, 2FA flags, password expiry tracking, and strength evaluation. Auto-mode (passwordless) for local use; upgradeable to password mode. All display output is masked. |\n| **Habit Tracking** | 6 frequency types (daily, weekly, Mon--Fri, specific days, every-N-days, monthly), grace days, automatic streak computation (current + longest), completion rates, mood ratings with notes, categories, and favorites. |\n| **Experience Recording** | 16 experience categories, 7 sentiment levels, emotion journey tracking (chronological emotion data points), growth outcomes (reframing failures as learning), follow-up reflections with sentiment shift, milestone classification for narrative identity, and guided reflection prompts. |\n| **Knowledge Management** | SM-2 spaced repetition algorithm with ease factors and intervals. 13 knowledge types, 6 mastery levels (Bloom's taxonomy), source provenance, application logging, knowledge graph (related/prerequisite/derived cards), confidence scores, and automatic decay risk calculation. |\n| **Lifestyle Information** | Preferences with evolution tracking (strength changes over time), daily/weekly routines with energy and mood tracking, contacts with relationship dynamics, and addresses with emotional associations. PII masking on all sensitive fields. |\n| **PersonalMemoryManager** | Unified facade with cross-module linking (5 link types: related, supports, inspired_by, contradicts, evolved_into), unified search across all modules, aggregate statistics, and due-item aggregation (overdue habits, due reviews, high decay risk). |\n\n---\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10 or later\n- pip\n\n### Install from source\n\n```bash\ngit clone https://github.com/sscctv/mcp-memory-suite.git\ncd mcp-memory-suite\npip install .\n```\n\nFor local embedding model support (offline vector embeddings via `sentence-transformers`):\n\n```bash\npip install \".[local-embedding]\"\n```\n\nFor development dependencies:\n\n```bash\npip install \".[dev]\"\n```\n\n### Dependencies\n\n| Package | Purpose |\n|---|---|\n| `numpy` | Numerical operations for embeddings and similarity computation |\n| `chromadb` | Vector database for dense retrieval |\n| `rank-bm25` | BM25 keyword search for sparse retrieval |\n| `scipy` | Scientific computing support |\n| `mcp` | Model Context Protocol server library |\n| `cryptography` | Argon2id KDF and Fernet encryption (personal memory vault) |\n| `pyyaml` | Configuration file parsing |\n| `sentence-transformers` *(optional)* | Local embedding model (`all-MiniLM-L6-v2`) |\n\nAfter installation, the `ai-memory-mcp` command is available on your PATH.\n\n---\n\n## Configuration\n\nThe server reads `config.yaml` from the current directory, the project root, or `~/.ai-memory/config.yaml`. If no file is found, built-in defaults are used.\n\n### Full `config.yaml` Reference\n\n```yaml\n# ── Storage ──────────────────────────────────────────────\nstorage:\n  sqlite_path: \"~/.ai-memory/memory.db\"   # SQLite database for core memories\n  chroma_path: \"~/.ai-memory/chroma\"      # ChromaDB directory for vector storage\n  wal_mode: true                           # SQLite WAL mode for concurrent reads\n\n# ── L1 Hot Cache ─────────────────────────────────────────\ncache:\n  max_size: 100            # LRU cache capacity (number of entries)\n  ttl_seconds: 3600        # Cache entry TTL (1 hour)\n\n# ── Embedding ────────────────────────────────────────────\nembedding:\n  api:                                      # Primary: OpenAI API (higher quality)\n    enabled: false\n    model: \"text-embedding-3-small\"\n    base_url: \"https://api.openai.com/v1\"\n    api_key_env: \"OPENAI_API_KEY\"           # Reads from environment variable\n    dimension: 1536\n  local:                                    # Fallback: local model (offline)\n    model: \"all-MiniLM-L6-v2\"\n    dimension: 384\n    cache_dir: \"~/.ai-memory/models\"\n  hash_fallback:                            # Last resort: hash-based embedding\n    dimension: 256\n\n# ── Three-Factor Reinforcement Weights ───────────────────\nweights:\n  w_retrieval: 0.3              # Call frequency weight (Hebbian)\n  w_adoption: 0.4               # Adoption rate weight (Dopamine)\n  w_feedback: 0.3               # Feedback score weight (Modulator)\n  max_access_count: 100         # Log compression denominator\n  feedback_half_life_days: 14   # Feedback decay half-life\n\n# ── Decay ────────────────────────────────────────────────\ndecay:\n  confidence_lambda: 0.03       # Ebbinghaus decay rate (~23-day half-life)\n  hebbian_decay: 0.99           # Hebbian connection decay per update\n  forget_threshold: 0.1         # Weight below this enters forget queue\n\n# ── Retrieval ────────────────────────────────────────────\nretrieval:\n  l1_top_k: 5                   # L1 seed node count\n  l2_max_expansion: 10          # L2 expansion candidate limit\n  l3_max_results: 10            # L3 final result limit\n  pagerank:\n    damping: 0.5                # Personalized PageRank damping factor\n    max_iterations: 3           # PageRank iterations\n    min_activation: 0.01        # Stop spreading below this activation\n  fusion:\n    vector_weight: 0.5          # Dense retrieval weight\n    bm25_weight: 0.3            # Sparse retrieval weight\n    graph_weight: 0.2           # Graph expansion weight\n  dedup_threshold: 0.85         # Similarity above this triggers merge\n\n# ── Token Budget ─────────────────────────────────────────\ntoken:\n  default_budget: 2000          # Default token budget for context\n  cold_start_budget: 800        # When memory count < 50\n  min_budget: 500\n  max_budget: 3000\n\n# ── Lifecycle ────────────────────────────────────────────\nlifecycle:\n  compress_after_days: 7        # Compress episodic memories after N days\n  archive_after_days: 30        # Move to archive after N days\n  audit_interval_days: 7        # Weekly audit\n  decay_interval_hours: 24      # Daily decay\n\n# ── Governance ───────────────────────────────────────────\ngovernance:\n  auto_merge_threshold: 0.90    # Auto-merge if similarity above this\n  auto_delete_criteria:\n    min_access_count: 0\n    max_importance: 0.5\n    require_negative_feedback: true\n  weak_edge_threshold: 0.05     # Prune Hebbian edges below this\n\n# ── MCP Server ───────────────────────────────────────────\nmcp:\n  server_name: \"ai-memory\"\n  server_version: \"0.1.0\"\n\n# ── Personal Memory Modules ──────────────────────────────\npersonal:\n  enabled: true\n  data_dir: \"~/.ai-memory/personal\"\n```\n\n### Data Directory\n\nAll data is stored under `~/.ai-memory/` by default:\n\n```\n~/.ai-memory/\n  memory.db              # Core memory SQLite database (WAL mode)\n  chroma/                # ChromaDB vector store\n  models/                # Cached local embedding model\n  config.yaml            # Optional config override\n  vault/                 # Encryption vault metadata\n    .vault_autokey       # Auto-mode Fernet key (0600 permissions)\n  personal/              # Personal memory module data\n    habits.db\n    experiences.db\n    knowledge.db\n    lifestyle.db\n    accounts.db\n    cross_links.db       # Cross-module link graph\n```\n\n---\n\n## Usage -- MCP Server Setup\n\nThe server communicates over **stdio transport** using the Model Context Protocol. It works with any MCP-compatible client.\n\n### Cursor\n\nAdd the following to your Cursor MCP configuration (Settings > MCP or `.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"ai-memory\": {\n      \"command\": \"ai-memory-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\nIf you installed in a virtual environment, use the full path:\n\n```json\n{\n  \"mcpServers\": {\n    \"ai-memory\": {\n      \"command\": \"/path/to/venv/bin/ai-memory-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to your Claude Desktop configuration file (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"ai-memory\": {\n      \"command\": \"ai-memory-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\n### Direct invocation\n\n```bash\nai-memory-mcp\n```\n\nThe server reads JSON-RPC 2.0 requests from stdin and writes responses to stdout. If the `mcp` Python package is not installed, a minimal stdio JSON-RPC fallback handler is used automatically.\n\n### Config file discovery\n\nOn startup, the server searches for `config.yaml` in this order:\n\n1. Current working directory (`./config.yaml`)\n2. Project root (relative to the package source)\n3. User home (`~/.ai-memory/config.yaml`)\n\nIf none is found, built-in defaults are used.\n\n---\n\n## MCP Tools Reference\n\nThe server exposes **24 MCP tools** in total: 9 core memory tools and 15 personal memory tools.\n\n### Core Memory Tools (9)\n\n| Tool | Description | Key Parameters |\n|---|---|---|\n| `memory_search` | Search memories through the full L1->L2->L3 retrieval pipeline. Returns a formatted context string within the token budget. | `query` (required), `project_id`, `max_tokens` |\n| `memory_add` | Add a new memory with automatic embedding, tag extraction, and write-time deduplication. Merges if similarity exceeds the threshold. | `content` (required), `memory_type`, `tags`, `importance`, `project_id` |\n| `memory_update` | Update an existing memory's content. Regenerates the embedding and refreshes the vector store. | `memory_id` (required), `content` |\n| `memory_delete` | Delete memories by ID or by tags. Soft-deletes in SQLite and removes from the vector store. | `memory_id`, `tags` |\n| `memory_list` | List memories with optional type and tag filters. Returns formatted entries with importance, access count, and tags. | `memory_type`, `tags`, `project_id`, `limit` |\n| `memory_stats` | Return memory statistics: total count, type distribution, and cache hit rate. | `project_id` |\n| `memory_confirm_usage` | Confirm that specific memories were used in the current session. Increments adoption count and strengthens Hebbian connections between co-activated memories. | `memory_ids` (required), `session_id` |\n| `memory_feedback` | Submit feedback for a memory. Updates feedback history and recomputes the reinforcement weight. | `memory_id` (required), `score` (required: -1, 0, +1), `comment` |\n| `memory_audit_report` | Generate a memory audit report with redundancy analysis, feedback summary, graph statistics, and a composite health score (0--1). | `project_id` |\n\n**Memory types:** `semantic`, `episodic`, `procedural`, `working`\n\n### Personal Memory Tools (15)\n\n#### Unified / Cross-Module (3)\n\n| Tool | Description | Key Parameters |\n|---|---|---|\n| `personal_search` | Search across all personal memory modules (accounts, habits, experiences, knowledge, lifestyle). Returns matching results from each. | `query` (required), `limit_per_module` |\n| `personal_overview` | Get an aggregate overview of all personal memory data: total counts per module and cross-module link count. | *(none)* |\n| `personal_due_items` | Get all items needing attention: overdue habits, due knowledge reviews, and high decay risk cards. | *(none)* |\n\n#### Account Vault (4)\n\n| Tool | Description | Key Parameters |\n|---|---|---|\n| `account_search` | Search stored accounts by platform, username, or email. Returns masked results (no passwords). | `query` (required), `limit` |\n| `account_get` | Get detailed information for a specific account by ID. Returns masked data. | `account_id` (required) |\n| `account_get_password` | Decrypt and return the plaintext password for a specific account. Use with caution. | `account_id` (required) |\n| `account_add` | Add a new account with an encrypted password. The password is encrypted before storage and never stored in plaintext. | `platform` (required), `username` (required), `password` (required), `category`, `email`, `url`, `notes`, `tags`, `password_hint`, `two_factor_enabled` |\n\n**Account categories:** `email`, `social`, `cloud`, `developer`, `finance`, `shopping`, `entertainment`, `work`, `education`, `government`, `other`\n\n#### Habit Tracking (3)\n\n| Tool | Description | Key Parameters |\n|---|---|---|\n| `habit_list` | List all habits with optional category filter and favorites-only mode. | `category`, `favorites_only` |\n| `habit_checkin` | Check in a habit for today or a specified date. Updates streak counters automatically. | `habit_id` (required), `date`, `note`, `mood` |\n| `habit_overdue` | Get all habits that are overdue for check-in. | *(none)* |\n\n**Habit frequencies:** `daily`, `weekly`, `mon_fri`, `specific_days`, `every_n_days`, `monthly`\n\n#### Knowledge Management (3)\n\n| Tool | Description | Key Parameters |\n|---|---|---|\n| `knowledge_search` | Search knowledge cards by title, content, or tags. | `query` (required), `limit` |\n| `knowledge_due` | Get knowledge cards that are due for review (SM-2 algorithm). | `limit` |\n| `knowledge_review` | Review a knowledge card, updating its SM-2 schedule. | `card_id` (required), `mastery_after` (required), `notes` |\n\n**Mastery levels:** `aware`, `familiar`, `proficient`, `mastered`\n\n#### Experience Recording (2)\n\n| Tool | Description | Key Parameters |\n|---|---|---|\n| `experience_search` | Search experiences by title, description, or tags. | `query` (required), `limit` |\n| `experience_add` | Record a new experience entry with optional lessons and tags. | `title` (required), `description`, `category`, `sentiment`, `importance`, `lessons`, `tags` |\n\n**Experience categories:** `career`, `relationship`, `travel`, `education`, `health`, `finance`, `creativity`, `failure`, `success`, `life_lesson`, `conflict`, `discovery`, `growth`, `loss`, `transition`, `other`\n\n---\n\n## Security\n\n### Account Vault Encryption\n\nThe account vault uses a two-layer encryption scheme:\n\n1. **Key Derivation:** The master encryption key is derived using **Argon2id** (RFC 9106) with 2 GiB memory cost, 4 lanes, and 1 iteration. If Argon2id is unavailable, **PBKDF2-HMAC-SHA256** with 1,200,000 iterations is used as a fallback. The salt is 16 bytes of cryptographic random.\n\n2. **Symmetric Encryption:** The derived key is used with **Fernet** (AES-128-CBC + HMAC-SHA256), which provides authenticated encryption -- tampering with ciphertext is detected on decryption.\n\n3. **Key Storage Modes:**\n   - **Auto mode (default):** A random Fernet key is generated on first use and stored in a permission-protected file (0600). No user password is required. Suitable for local-only plugins where OS file permissions provide the first line of defense.\n   - **Password mode (optional):** The user sets a master password, validated via Argon2id key derivation against a stored verification token. More secure for shared devices. Users can upgrade from auto mode at any time via `upgrade_to_password()`.\n\n4. **Sensitive fields are never stored in plaintext.** Passwords, security answers, API keys, and recovery codes are encrypted as Fernet tokens. Non-sensitive fields (platform, category, tags) remain in plaintext for searchability.\n\n### Data Masking\n\nAll display output from personal memory tools applies configurable masking:\n\n| Data Type | Masking Example |\n|---|---|\n| Passwords | Always fully masked (`--------`) |\n| Emails | `u***@example.com` (first char + domain visible) |\n| Phone numbers | `138****8888` (first 3 + last 4 digits) |\n| API keys | `sk-****...****ab2f` (first 4 + last 4 characters) |\n| Credit cards | `**** **** **** 1234` (last 4 digits only) |\n| Usernames | `user***` (partial masking based on length) |\n| ID cards | `110***********1234` (first 3 + last 4 digits) |\n\nThree masking levels are available: `full` (complete masking), `partial` (default, shows some characters), and `none` (no masking, use with caution).\n\n### Privacy Levels\n\nAll personal data entries carry a `privacy_level` field for access control:\n\n- `public` -- Shareable\n- `personal` -- Default for habits, experiences, knowledge, preferences\n- `sensitive` -- Default for contacts and addresses\n- `highly_sensitive` -- Reserved for the most sensitive data\n\n### File Permissions\n\nVault directory and key files are created with restrictive permissions:\n\n- Vault directory: `0700` (owner only)\n- Key/metadata files: `0600` (owner read/write only)\n\n---\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/sscctv/mcp-memory-suite.git\ncd mcp-memory-suite\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\nThe project includes 1204 tests with 91% code coverage.\n\n```bash\n# Run all tests\npytest\n\n# Run with verbose output\npytest -v\n\n# Run a specific test file\npytest tests/test_core.py\n```\n\n### Test Organization\n\n| Test File | Coverage Area |\n|---|---|\n| `tests/test_core.py` | Core memory system: storage, retrieval, weights, Hebbian, governance, bootstrap |\n| `tests/test_personal.py` | Personal memory stores: habits, experiences, knowledge, lifestyle |\n| `tests/test_personal_mcp.py` | Personal MCP tool dispatcher and tool definitions |\n| `tests/test_auto_crypto.py` | Vault auto-mode encryption/decryption |\n| `tests/test_habits.py` | Habit tracking: check-ins, streaks, overdue detection |\n| `tests/test_experiences.py` | Experience recording: categories, sentiments, reflections |\n| `tests/test_knowledge.py` | Knowledge management: SM-2 scheduling, decay risk |\n| `tests/test_lifestyle.py` | Lifestyle: preferences, routines, contacts, addresses |\n| `tests/test_manager.py` | PersonalMemoryManager: cross-module linking, unified search |\n| `tests/test_cli.py` / `test_cli_extended.py` | CLI commands: all subcommands and edge cases |\n| `tests/test_mcp_extended.py` | Extended MCP server tool testing |\n| `tests/test_review.py` | Scheduled review system: daily/weekly reports, scheduler |\n| `tests/test_notifications.py` | Notification and reminder system |\n| `tests/test_backup.py` | Backup and recovery system |\n| `tests/test_sync.py` | Multi-device synchronization |\n| `tests/test_import_export.py` / `test_import_export_extended.py` | Data import/export |\n| `tests/test_web_server.py` | Web UI server |\n| `tests/test_coverage_gaps.py` | Edge cases and coverage gap fills |\n\n### Coverage Report\n\n```bash\n# Generate coverage report\npytest --cov=memory_plugin --cov-report=html\n# Open htmlcov/index.html in a browser\n```\n\n### Benchmarks\n\nBenchmark scripts are available in the `benchmarks/` directory:\n\n```bash\npython benchmarks/benchmark_retrieval.py    # Retrieval pipeline performance\npython benchmarks/benchmark_performance.py  # Overall system performance\n```\n\nResults are saved to `benchmarks/retrieval_report.json` and `benchmarks/performance_report.json`.\n\n---\n\n## Project Structure\n\n```\nai-memory-mcp/\n|-- config.yaml                        # Main configuration file\n|-- pyproject.toml                     # Package metadata, dependencies, entry points\n|-- src/\n|   `-- memory_plugin/\n|       |-- __init__.py\n|       |-- mcp_server.py              # MCP server: 9 core tool handlers, lifecycle\n|       |-- personal_mcp_tools.py      # 15 personal tool definitions + dispatcher\n|       |-- config.py                  # Configuration dataclasses, YAML loading\n|       |-- models.py                  # MemoryEntry, Feedback, Provenance, SearchResult\n|       |-- embedding.py              # Embedding provider (API / local / hash fallback)\n|       |-- weights.py                # Three-factor reinforcement weight calculator\n|       |-- hebbian.py                # Hebbian connection weight updater\n|       |-- governance.py             # Audit, redundancy/contradiction detection, health score\n|       |-- lifecycle.py             # Decay, compression, forgetting, archiving\n|       |-- bootstrap.py             # Codebase scanner for cold-start memory extraction\n|       |-- utils.py                  # Cosine similarity, token counting, tag extraction\n|       |-- retrieval/\n|       |   |-- __init__.py\n|       |   |-- l1_direct.py          # L1: vector + BM25 parallel recall, fusion\n|       |   |-- l2_expansion.py       # L2: Personalized PageRank spreading activation\n|       |   |-- l3_context.py         # L3: weighted scoring, token-budget packing, formatting\n|       |   `-- fusion.py             # Multi-channel score fusion + semantic deduplication\n|       |-- storage/\n|       |   |-- __init__.py\n|       |   |-- sqlite_store.py       # SQLite storage with WAL mode\n|       |   |-- vector_store.py       # ChromaDB vector storage\n|       |   `-- cache.py              # LRU hot cache with TTL\n|       `-- personal/\n|           |-- __init__.py\n|           |-- manager.py            # PersonalMemoryManager: unified facade, cross-module linking\n|           |-- crypto.py             # VaultCrypto: Argon2id + Fernet encryption\n|           |-- masking.py            # DataMasking: PII masking utilities\n|           |-- password_utils.py     # Password generator + strength evaluator\n|           |-- shared_types.py       # PrivacyLevel, ModuleType, LinkType enums\n|           |-- account_models.py     # AccountEntry, SecurityQuestion, APIKeyEntry\n|           |-- account_store.py      # AccountStore: encrypted CRUD operations\n|           |-- habits_models.py      # Habit, HabitCheckIn, frequency/category enums\n|           |-- habits_store.py       # HabitStore: check-ins, streaks, overdue detection\n|           |-- experiences_models.py # Experience, EmotionPoint, GrowthOutcome, Reflection\n|           |-- experiences_store.py  # ExperienceStore: CRUD, search, stats\n|           |-- knowledge_models.py   # KnowledgeCard, ReviewRecord, SM-2 types\n|           |-- knowledge_store.py    # KnowledgeStore: SM-2 scheduling, decay risk\n|           |-- lifestyle_models.py   # Preference, Routine, Contact, Address\n|           |-- lifestyle_store.py    # LifestyleStore: multi-entity storage\n|           |-- backup.py             # Backup and recovery with retention\n|           |-- notifications.py      # Reminder engine: habits, reviews, expiries\n|           |-- review.py             # Scheduled review: daily/weekly reports\n|           |-- sync.py              # Multi-device sync via JSON snapshots\n|           `-- web_server.py        # Web UI server for browser access\n|-- tests/                             # 1204 tests, 91% coverage\n|   |-- conftest.py\n|   |-- test_core.py\n|   |-- test_personal.py\n|   |-- test_personal_mcp.py\n|   |-- test_auto_crypto.py\n|   |-- test_habits.py\n|   |-- test_experiences.py\n|   |-- test_knowledge.py\n|   |-- test_lifestyle.py\n|   |-- test_manager.py\n|   |-- test_cli.py\n|   |-- test_cli_extended.py\n|   |-- test_mcp_extended.py\n|   |-- test_review.py\n|   |-- test_notifications.py\n|   |-- test_backup.py\n|   |-- test_sync.py\n|   |-- test_import_export.py\n|   |-- test_import_export_extended.py\n|   |-- test_web_server.py\n|   `-- test_coverage_gaps.py\n|-- benchmarks/                        # Performance benchmarking scripts\n|-- data/                              # Runtime data (vault, databases)\n`-- coverage.json                      # Coverage report data\n```\n\n---\n\n## License\n\nThis project is licensed under the MIT License -- see the [LICENSE](LICENSE) file for details.\n"}