{"id":32517894,"url":"https://github.com/rand/mnemosyne","last_synced_at":"2026-04-29T16:06:47.825Z","repository":{"id":320894177,"uuid":"1083620684","full_name":"rand/mnemosyne","owner":"rand","description":"Mnemosyne is a agentic memory and orchestration system designed to provide Claude Code with persistent semantic memory across sessions.","archived":false,"fork":false,"pushed_at":"2025-11-23T20:08:20.000Z","size":5639,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-23T20:25:45.356Z","etag":null,"topics":["agents","claude-code","memory","orchestration"],"latest_commit_sha":null,"homepage":"https://rand.github.io/mnemosyne/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rand.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security/AUDIT_2025_PHASE1.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-26T11:58:46.000Z","updated_at":"2025-11-23T20:08:24.000Z","dependencies_parsed_at":"2025-10-26T16:28:42.594Z","dependency_job_id":null,"html_url":"https://github.com/rand/mnemosyne","commit_stats":null,"previous_names":["rand/mnemosyne"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/rand/mnemosyne","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rand%2Fmnemosyne","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rand%2Fmnemosyne/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rand%2Fmnemosyne/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rand%2Fmnemosyne/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rand","download_url":"https://codeload.github.com/rand/mnemosyne/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rand%2Fmnemosyne/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32432980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T13:34:34.882Z","status":"ssl_error","status_checked_at":"2026-04-29T13:34:29.830Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","claude-code","memory","orchestration"],"created_at":"2025-10-28T03:00:56.551Z","updated_at":"2026-04-29T16:06:47.818Z","avatar_url":"https://github.com/rand.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mnemosyne\n\n**High-performance agentic memory system for Claude Code's multi-agent orchestration**\n\nMnemosyne provides persistent semantic memory with sub-millisecond retrieval, built in Rust with LibSQL vector search and PyO3 Python bindings.\n\n---\n\n## Features\n\n### Core Memory System\n- **Project-Aware**: Automatic namespace detection from git repositories and CLAUDE.md\n- **Semantic Search**: LibSQL vector embeddings + full-text search (FTS5) + graph connectivity\n- **Type System**: Insight, Architecture, Decision, Task, Reference memory types\n- **Graph Linking**: Automatic bidirectional relationship management\n- **Privacy-First**: Local-only storage with optional privacy-preserving evaluation\n\n### Multi-Agent Orchestration\n- **Ractor Actors**: 4 specialized agents (Orchestrator, Optimizer, Reviewer, Executor)\n- **LLM-Enhanced Reviewer**: Automatic requirement extraction, semantic validation, intent verification with Claude API\n- **Work Queue**: Dependency-aware scheduling with priority management\n- **Quality Gates**: Automated test verification, anti-pattern detection, constraint validation, requirement traceability\n- **Deadlock Resolution**: Priority-based preemption (60s timeout)\n- **Sub-Agent Spawning**: Parallel work execution across child actors\n- **Event Persistence**: Complete audit trail of orchestration events with SSE broadcasting\n\n### Distributed Coordination\n- **Peer Discovery**: Automatic peer discovery on local network via `mnemosyne peer invite/join`\n- **Work Delegation**: Seamless offloading of tasks to available peers\n- **Iroh Networking**: P2P encrypted communication layer for secure direct connections\n\n### Network Visualization\n- **Network Graph**: Visual representation of connected peers and topology via `mnemosyne graph`\n- **Real-time Status**: Connection latency, bandwidth, and peer health monitoring\n- **Topology Awareness**: Automatic detection of network partitions and routing paths\n\n### Evolution System\n- **Consolidation**: Detect and merge duplicate/similar memories with LLM-assisted analysis\n- **Importance Scoring**: Graph-based importance recalibration\n- **Link Decay**: Time-based link strength management\n- **Archival**: Automatic cleanup of low-value memories\n- **Supersede**: Track memory replacements with audit trail\n\n### Evaluation System *(Privacy-Preserving)*\n- **Feedback Collection**: Implicit signals (access, edit, commit) with privacy-preserving task hashing\n- **Feature Extraction**: 13 privacy-preserving features (keyword overlap, semantic similarity, recency, etc.)\n- **Online Learning**: Hierarchical weight adaptation (session → project → global)\n- **Relevance Scoring**: Context-aware ranking with learned weights\n\n### Interactive Collaborative Space (ICS)\n**Integrated context editor accessible via `mnemosyne edit` or `/ics` slash command**\n\n- **CRDT Editing**: Automerge-based collaborative text editor\n- **Template System**: 5 built-in templates (API, Architecture, Bugfix, Feature, Refactor)\n- **Panels**: Memory browser, diagnostics, proposals, typed holes\n- **Syntax Highlighting**: Tree-sitter 0.23 based highlighting for 13 languages (Rust, Python, Go, TypeScript, JavaScript, JSON, TOML, YAML, Markdown, Bash, C, C++, Zig)\n- **Semantic Highlighting (3-Tier System)**:\n  - **Tier 1: Structural** (\u003c5ms real-time) - XML tags, RFC 2119 constraints, modality/hedging, ambiguity detection, domain patterns\n  - **Tier 2: Relational** (\u003c200ms incremental) - Named entities, relationships, semantic roles, coreference resolution, anaphora\n  - **Tier 3: Analytical** (2s+ background, optional) - Discourse analysis, contradiction detection, pragmatics, LLM-powered\n- **ICS Patterns**: `#file`, `@symbol`, `?hole` with color-coded highlighting\n- **Hybrid Highlighting**: Combines tree-sitter syntax with semantic pattern detection (3-layer priority system)\n- **Vim Mode**: Complete vi/vim keybindings with modal editing (14 movement commands: w/b/e, f/F/t/T, PageUp/Down, gg/G)\n- **Semantic Analysis**: Real-time triple extraction, typed hole detection, dependency graphs\n- **Undo/Redo**: Transaction-based history with Automerge\n- **Claude Code Integration**: Seamless handoff via file-based coordination protocol\n\n**Usage**:\n```bash\n# From Claude Code session\n/ics context.md\n/ics --template feature new-feature.md\n/ics --panel memory --template api auth.md\n\n# Command-line\nmnemosyne edit context.md\nmnemosyne edit --template architecture decision.md\nmnemosyne ics --readonly --panel diagnostics review.md\n```\n\nSee [docs/guides/ICS_INTEGRATION.md](docs/guides/ICS_INTEGRATION.md) for complete guide.\n\n### Dashboard \u0026 Monitoring\n- **mnemosyne-dash**: Real-time monitoring dashboard with clean 4-panel layout (redesigned from \"static wall of garbage\")\n- **Panels**: System Overview (health metrics), Activity Stream (filtered event log), Agent Details (per-agent status), Operations (CLI command history)\n- **Smart Filtering**: Intelligent noise reduction (heartbeats hidden by default), 8 event categories, compound filter logic\n- **Event Correlation**: Links start→complete events with duration tracking, automatic slow operation detection\n- **Real-time Updates**: Server-Sent Events (SSE) streaming from API server with zero-latency event delivery\n- **Interactive Controls**: Full keyboard navigation (panel toggles, clear history, focus modes)\n- **HTTP API Server** (`:3000`): Automatic REST API with owner/client mode for multiple instances\n- **Event Streaming**: Real-time coordination via SSE for monitoring and cross-instance event forwarding\n- **Production Quality**: 124+ tests, 6,100+ lines of code, comprehensive error handling\n\nSee [docs/DASHBOARD.md](docs/DASHBOARD.md) for complete documentation.\n\n### gRPC Remote Access (RPC Server)\n**Production-ready gRPC server for remote access to mnemosyne's memory system**\n\n- **Full CRUD Operations**: Store, retrieve, update, delete memories via gRPC\n- **Advanced Search**: Semantic search (vector embeddings), graph traversal, hybrid recall\n- **Streaming APIs**: Progressive results for large datasets, progress tracking for slow operations\n- **Type-Safe Protocol**: Protocol Buffers ensure schema validation and backward compatibility\n- **Multi-Language Support**: Client libraries for Python, Rust, Go, and any gRPC-compatible language\n- **Production Features**: Comprehensive error handling, input validation, rate limiting\n\n**Usage**:\n```bash\n# Start RPC server on default port (50051)\nmnemosyne-rpc\n\n# Custom configuration\nmnemosyne-rpc --host 0.0.0.0 --port 9090 --enable-llm\n\n# With custom database\nmnemosyne-rpc --db-path /path/to/mnemosyne.db\n```\n\n**Client Example (Python)**:\n```python\nimport grpc\nfrom mnemosyne.v1 import memory_pb2, memory_pb2_grpc\n\n# Connect and store a memory\nchannel = grpc.insecure_channel('localhost:50051')\nstub = memory_pb2_grpc.MemoryServiceStub(channel)\n\nresponse = stub.StoreMemory(memory_pb2.StoreMemoryRequest(\n    content=\"Important architectural decision\",\n    namespace=memory_pb2.Namespace(\n        project=memory_pb2.ProjectNamespace(name=\"my-project\")\n    ),\n    importance=9,\n    tags=[\"architecture\", \"decision\"]\n))\nprint(f\"Stored memory: {response.memory_id}\")\n```\n\nSee [src/rpc/README.md](src/rpc/README.md) for complete API documentation, deployment guides, and client examples.\n\n---\n\n## Quick Start\n\n### Installation\n\n**Automated Installation** (Recommended):\n```bash\n# Clone repository\ngit clone https://github.com/yourusername/mnemosyne.git\ncd mnemosyne\n\n# Run installation script\n./scripts/install/install.sh\n\n# Installation will:\n# - Build release binary\n# - Install to ~/.local/bin\n# - Initialize database\n# - Configure MCP server\n# - Optionally set up API keys\n# - Detect and optionally install Nerd Fonts for icon support\n```\n\n**Icon System**: Mnemosyne uses Nerd Font icons (Font Awesome) for a polished CLI experience with automatic fallback to ASCII. For best results, install [JetBrainsMono Nerd Font](https://www.nerdfonts.com/). See [docs/ICONS.md](docs/ICONS.md) for details.\n\n**Manual Installation**:\n```bash\n# Prerequisites: Rust 1.75+, Python 3.10-3.14, uv\ncargo build --release\n\n# Copy binary to PATH\ncp target/release/mnemosyne ~/.local/bin/\n\n# Initialize database\nmnemosyne init\n\n# Configure secrets (optional for LLM enrichment)\nmnemosyne secrets set --provider anthropic --key sk-ant-...\n```\n\n**Uninstallation**:\n```bash\n# Remove binary and MCP config (preserves data)\n./scripts/install/uninstall.sh\n\n# Remove everything including data\n./scripts/install/uninstall.sh --purge\n```\n\n### Basic Usage\n\n**Store memories**:\n```bash\n# Store with automatic namespace detection\nmnemosyne remember --content \"User prefers concise code reviews\" --importance 8\n\n# Store with explicit namespace\nmnemosyne remember \"Database uses LibSQL with vector search\" \\\n  --namespace \"project:mnemosyne\" \\\n  --type architecture \\\n  --importance 9\n```\n\n**Search memories**:\n```bash\n# Semantic search\nmnemosyne recall --query \"code review preferences\"\n\n# Search with namespace filter\nmnemosyne recall \"database\" --namespace \"project:mnemosyne\"\n\n# Limit results\nmnemosyne recall \"architecture decisions\" --limit 5\n```\n\n**Evolution operations**:\n```bash\n# Consolidate duplicate memories\nmnemosyne evolve consolidate\n\n# Recalibrate importance scores\nmnemosyne evolve importance\n\n# Archive old/low-value memories\nmnemosyne evolve archive\n```\n\n**Interactive Collaborative Space (Standalone)**:\n```bash\n# Launch standalone ICS context editor\nmnemosyne-ics\n\n# Create from template\nmnemosyne-ics --template feature\n\n# Open existing file\nmnemosyne-ics path/to/context.md\n\n# Read-only mode (view memory dumps)\nmnemosyne-ics --read-only path/to/dump.md\n\n# Features:\n# - Full terminal ownership (no conflicts)\n# - Template system (api, architecture, bugfix, feature, refactor)\n# - Storage backend integration\n# - Semantic highlighting (3-tier system)\n# - Vim mode with modal editing\n```\n\n**Real-time Monitoring Dashboard**:\n```bash\n# API server starts automatically with first MCP instance (owner mode)\n# Launch monitoring dashboard (connects to http://localhost:3000 by default)\nmnemosyne-dash\n\n# Custom configuration\nmnemosyne-dash --api http://localhost:3000 --refresh 500\n\n# Features:\n# - Clean 4-panel layout (System Overview, Activity Stream, Agent Details, Operations)\n# - Smart event filtering (heartbeats hidden by default, 8 categories)\n# - Event correlation (links start→complete with durations)\n# - Real-time SSE updates with zero latency\n# - Full keyboard control (0-3 panel toggles, c to clear, q to quit)\n# - Automatic slow operation and failure detection\n# - 124+ tests, production-ready monitoring\n\n# See docs/DASHBOARD.md for keyboard shortcuts and advanced usage\n```\n\n**TUI Wrapper Mode** (Deprecated in v2.1.0):\n```bash\n⚠️ Deprecated: Use mnemosyne-ics + mnemosyne-dash instead\nSee docs/guides/migration.md for migration guide\n\n# Launch TUI with command palette, ICS editor, and agent dashboard\nmnemosyne tui\n\n# Start with ICS panel visible\nmnemosyne tui --with-ics\n\n# Features:\n# - Helix-style command palette (Ctrl+P)\n# - ICS editor with markdown highlighting (Ctrl+E)\n# - Real-time agent dashboard (Ctrl+D)\n# - Context-aware help overlay (?)\n# - Pattern highlighting: #file.rs @symbol ?hole\n```\n\n**Orchestration** (Python agents):\n```bash\n# Run orchestration workflow\nmnemosyne orchestrate --session-id dev-001 --work-items plan.json\n```\n\n---\n\n## Architecture\n\n### Storage Layer\n- **LibSQL**: SQLite-compatible with native vector search (sqlite-vec)\n- **Embeddings**:\n  - Local: fastembed (nomic-embed-text-v1.5, 768d)\n  - Remote: Voyage AI (voyage-3-large, 1536d)\n- **Search Config**: Hybrid scoring (semantic 70%, FTS 20%, graph 10%)\n- **Performance**: 2.25ms avg operations, 0.88ms list, 1.61ms search\n- **Read-Only Support**: Auto-detects and handles read-only databases gracefully\n\n### Multi-Agent System\n```\n┌─────────────────────────────────────────────────────┐\n│           Multi-Agent Orchestration                  │\n│                                                      │\n│  ┌──────────────┐    ┌──────────────┐              │\n│  │ Orchestrator │◄──►│  Optimizer   │              │\n│  │  (Ractor)    │    │  (Ractor)    │              │\n│  └──────┬───────┘    └──────┬───────┘              │\n│         │                   │                        │\n│         │              Skill Discovery               │\n│         ▼                   ▼                        │\n│  ┌──────────────┐    ┌──────────────┐              │\n│  │   Executor   │◄──►│   Reviewer   │              │\n│  │  (Ractor)    │    │  (Ractor)    │              │\n│  │  + Sub-agents│    │ Quality Gates│              │\n│  └──────────────┘    └──────────────┘              │\n└─────────────────────────────────────────────────────┘\n                         │\n                         ▼\n┌─────────────────────────────────────────────────────┐\n│       Storage + Evolution + Evaluation               │\n│                                                      │\n│  LibSQL  ◄──►  Consolidation  ◄──►  Evaluation     │\n│  Vector       (Deduplication)     (Learning Weights)│\n└─────────────────────────────────────────────────────┘\n```\n\n**Actor Responsibilities**:\n- **Orchestrator**: Work queue, deadlock detection/resolution, phase transitions\n- **Optimizer**: Context management, dynamic skill discovery, memory loading\n- **Reviewer**: Quality gates, test verification, anti-pattern detection\n- **Executor**: Work execution, sub-agent spawning for parallel work\n\n---\n\n## CLI Reference\n\n### Memory Operations\n```bash\n# Store memory\nmnemosyne remember [OPTIONS] \u003cCONTENT\u003e\n  --namespace \u003cNS\u003e      Namespace (auto-detected from git/CLAUDE.md)\n  --importance \u003c1-10\u003e   Importance score (default: 5)\n  --type \u003cTYPE\u003e         Memory type (insight|architecture|decision|task|reference)\n  --tags \u003cTAGS\u003e         Comma-separated tags\n  --links \u003cIDS\u003e         Link to existing memory IDs\n\n# Search memories\nmnemosyne recall [OPTIONS] \u003cQUERY\u003e\n  --namespace \u003cNS\u003e      Filter by namespace\n  --limit \u003cN\u003e           Max results (default: 10)\n  --min-importance \u003cN\u003e  Minimum importance score\n\n# Generate embeddings\nmnemosyne embed \u003cTEXT\u003e\n  --model \u003cMODEL\u003e       Embedding model (local|remote)\n```\n\n### Evolution\n```bash\n# Run evolution jobs\nmnemosyne evolve \u003cOPERATION\u003e\n  consolidate           Detect and merge duplicate memories\n  importance            Recalibrate importance scores\n  archive               Archive low-value memories\n  links                 Update link decay scores\n```\n\n### Orchestration\n```bash\n# Run orchestration workflow\nmnemosyne orchestrate [OPTIONS]\n  --session-id \u003cID\u003e     Session identifier\n  --work-items \u003cFILE\u003e   Work items JSON file\n```\n\n### ICS (Integrated Context Studio) - Standalone Binary\n```bash\n# Launch standalone ICS context editor\nmnemosyne-ics [OPTIONS] [FILE]\n  --template \u003cTEMPLATE\u003e  Use template (api|architecture|bugfix|feature|refactor)\n  --read-only            Open in read-only mode\n  --vim-mode             Enable vim keybindings (default: on)\n  --theme \u003cTHEME\u003e        Color theme (dark|light)\n\n# Features:\n# • Full terminal ownership (no conflicts with Claude Code)\n# • Template system for common contexts\n# • 3-tier semantic highlighting (\u003c5ms→\u003c200ms→2s+)\n# • Storage backend integration\n# • Vim modal editing\n# • Pattern syntax: #file.rs @symbol ?hole\n```\n\n### Monitoring Dashboard - Standalone Binary\n```bash\n# Launch real-time monitoring dashboard\nmnemosyne-dash [OPTIONS]\n  --api-url \u003cURL\u003e       API server URL (default: http://localhost:3000)\n  --refresh-rate \u003cMS\u003e   Update interval (default: 100ms)\n\n# API server starts automatically with first MCP instance\n# No manual startup required\n\n# Features:\n# • Live agent activity via SSE across all MCP instances\n# • Color-coded agent states\n# • System statistics (memory, CPU, context)\n# • Event log with scrollback\n# • Auto-reconnect on disconnect\n```\n\n### API Server (Automatic)\n```bash\n# MCP server automatically starts HTTP API on first instance (owner mode)\n# Subsequent instances connect as clients and forward events via HTTP\nmnemosyne serve\n\n# Owner mode (first instance):\n# • Binds port 3000 (or 3001-3010 if 3000 unavailable)\n# • Starts API server with SSE event streaming\n# • Broadcasts events locally\n\n# Client mode (subsequent instances):\n# • Detects existing API server via health check\n# • Forwards events via POST /events/emit\n# • No port conflicts - seamless multi-instance support\n\n# Endpoints:\n# GET  /health                Health check (used for auto-detection)\n# GET  /events                SSE event stream (real-time)\n# POST /events/emit           Event forwarding (client mode)\n# GET  /state/agents          List agent states\n# GET  /state/context-files   Context files across instances\n\n# Features:\n# • Automatic owner/client mode detection\n# • Zero-configuration multi-instance support\n# • Event forwarding via HTTP POST (100ms timeout, fire-and-forget)\n# • REST API with Axum + Server-Sent Events (SSE)\n# • CORS support for web clients\n```\n\n### TUI (Terminal User Interface) - Deprecated\n```bash\n⚠️ Deprecated in v2.1.0: Use mnemosyne-ics + mnemosyne-dash instead\nSee docs/guides/migration.md for migration guide\n\n# Launch enhanced TUI wrapper mode\nmnemosyne tui [OPTIONS]\n  --with-ics            Start with ICS panel visible\n  --no-dashboard        Disable agent dashboard\n\n# TUI Features:\n# • Command Palette (Ctrl+P): Helix-style fuzzy command selector\n# • ICS Editor (Ctrl+E): Integrated Context Studio with highlighting\n# • Agent Dashboard (Ctrl+D): Real-time agent status and work queue\n# • Help Overlay (?): Context-aware keyboard shortcuts\n# • Status Bar: Dynamic action hints based on current mode\n\n# Keyboard Shortcuts:\n# General Navigation:\n#   Ctrl+P          Open command palette\n#   Ctrl+E          Toggle ICS panel\n#   Ctrl+D          Toggle dashboard\n#   Ctrl+Q          Quit application\n#   ?               Show help overlay\n\n# ICS Mode:\n#   Ctrl+Enter      Submit refined context to Claude\n#   Ctrl+S          Save edited document\n#   Pattern syntax:\n#     #file.rs      File reference (blue, bold)\n#     @symbol       Symbol reference (green, bold)\n#     ?interface    Typed hole (yellow, bold)\n```\n\n### Configuration\n```bash\n# Initialize database\nmnemosyne init [PATH]\n\n# Manage secrets\nmnemosyne secrets set --provider \u003cPROVIDER\u003e --key \u003cKEY\u003e\nmnemosyne secrets list\n\n# Database info\nmnemosyne info\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n```bash\n# Database\nexport DATABASE_URL=\"sqlite:///path/to/mnemosyne.db\"\n\n# API Keys (for LLM enrichment)\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\nexport VOYAGE_API_KEY=\"pa-...\"   # For remote embeddings\n\n# Logging\nexport RUST_LOG=\"info\"           # debug|info|warn|error\n```\n\n### Search Configuration\n```rust\nSearchConfig {\n    semantic_weight: 0.7,  // 70% semantic similarity\n    fts_weight: 0.2,       // 20% keyword match\n    graph_weight: 0.1,     // 10% link connectivity\n}\n```\n\n### Connection Modes\n```rust\nConnectionMode::Local(path)              // Local SQLite file\nConnectionMode::LocalReadOnly(path)      // Read-only database\nConnectionMode::Remote { url, token }    // Remote LibSQL/Turso\nConnectionMode::EmbeddedReplica { ... }  // Local replica with sync\n```\n\n---\n\n## Documentation\n\n### Getting Started\n- [README.md](README.md) - Project overview and quick start (this file)\n- [QUICK_START.md](QUICK_START.md) - Get up and running in 5 minutes\n- [INSTALL.md](INSTALL.md) - Detailed installation guide\n\n### For Agents/Developers\n- **[AGENT_GUIDE.md](AGENT_GUIDE.md)** - **START HERE** - Comprehensive development guide\n- [docs/INDEX.md](docs/INDEX.md) - Documentation navigation hub\n- [docs/TYPES_REFERENCE.md](docs/TYPES_REFERENCE.md) - Complete type system reference\n- [docs/STORAGE_SCHEMA.md](docs/STORAGE_SCHEMA.md) - Database schema and query patterns\n\n### Core System\n- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture and design decisions\n- [ORCHESTRATION.md](ORCHESTRATION.md) - Multi-agent coordination guide\n- [MCP_SERVER.md](MCP_SERVER.md) - MCP protocol integration\n\n### Features\n- [docs/features/EVOLUTION.md](docs/features/EVOLUTION.md) - Memory evolution system\n- [docs/features/VECTOR_SEARCH.md](docs/features/VECTOR_SEARCH.md) - Semantic search implementation\n- [docs/features/PRIVACY.md](docs/features/PRIVACY.md) - Privacy-preserving evaluation\n- [docs/features/ICS_README.md](docs/features/ICS_README.md) - Integrated Context Studio\n- [docs/features/semantic_highlighting.md](docs/features/semantic_highlighting.md) - 3-tier highlighting system\n\n### Guides\n- [docs/guides/migration.md](docs/guides/migration.md) - Migration from TUI to composable tools\n- [docs/guides/llm-reviewer.md](docs/guides/llm-reviewer.md) - LLM reviewer system\n- [docs/guides/llm-reviewer-setup.md](docs/guides/llm-reviewer-setup.md) - Setup and troubleshooting\n- [docs/guides/workflows.md](docs/guides/workflows.md) - Common development workflows\n\n### Specifications\n- [docs/specs/background-processing-spec.md](docs/specs/background-processing-spec.md) - Tier 3 background processing\n- [docs/specs/ics-integration-spec.md](docs/specs/ics-integration-spec.md) - ICS integration specification\n- [docs/specs/incremental-analysis-spec.md](docs/specs/incremental-analysis-spec.md) - Incremental semantic analysis\n- [docs/specs/semantic-highlighter-test-plan.md](docs/specs/semantic-highlighter-test-plan.md) - Testing strategy\n- [docs/specs/tier3-llm-integration-spec.md](docs/specs/tier3-llm-integration-spec.md) - LLM integration architecture\n\n### Development\n- [CHANGELOG.md](CHANGELOG.md) - Version history\n- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions\n- [TODO_TRACKING.md](TODO_TRACKING.md) - Development progress tracking\n- [docs/BUILD_OPTIMIZATION.md](docs/BUILD_OPTIMIZATION.md) - Build performance tuning\n\n---\n\n## Testing\n\n```bash\n# Unit tests\ncargo test --lib\n\n# Integration tests\ncargo test --test integration_ics --features test-utils\n\n# E2E tests\nbash tests/e2e/human_workflow_1_new_project.sh\nbash tests/e2e/agentic_workflow_1_orchestrator.sh\nbash tests/e2e/recovery_1_graceful_degradation.sh\n\n# All E2E tests\nfind tests/e2e -name '*.sh' -executable -exec {} \\;\n\n# With coverage\ncargo tarpaulin --lib --out Html\n```\n\n---\n\n## Troubleshooting\n\n### macOS \"killed\" Error\n\nIf you see `zsh: killed  mnemosyne` when trying to run the binary:\n\n**Quick Fix**:\n```bash\nxattr -d com.apple.provenance ~/.cargo/bin/mnemosyne\ncodesign --force --sign - ~/.cargo/bin/mnemosyne\n```\n\n**Root Cause**: macOS Gatekeeper invalidates code signatures when binaries are relocated (e.g., by `cargo install`). The binary in `target/release/` works fine, but the installed copy in `~/.cargo/bin/` gets killed by taskgated.\n\n**Permanent Fix**: Always use the install script, which handles re-signing automatically:\n```bash\n./scripts/install/install.sh\n```\n\n**Quick rebuild during development**:\n```bash\n./scripts/build-and-install.sh\n```\n\nFor more troubleshooting help, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).\n\n---\n\n## Performance\n\n**Storage Operations** (PyO3 vs subprocess):\n- Store: 2.25ms avg (was 20-50ms) - **10-20x faster**\n- List: 0.88ms avg (\u003c1ms target) - **22-56x faster**\n- Search: 1.61ms avg (was 30-60ms) - **18-37x faster**\n\n**Memory**:\n- Rust memory management (no GC pauses)\n- Zero-copy data passing for agent messages\n- Efficient vector storage with LibSQL\n\n**Scalability**:\n- Sub-agent spawning for parallel work\n- Deadlock prevention via dependency-aware scheduling\n- Context preservation at 75% utilization threshold\n\n---\n\n## Contributing\n\n1. Follow Work Plan Protocol (Phases 1-4: Prompt → Spec → Plan → Artifacts)\n2. Use Beads for task tracking: `bd import -i .beads/issues.jsonl`\n3. Quality gates: Tests pass, no anti-patterns, constraints maintained\n4. Commit before testing (never test uncommitted code)\n5. Run `cargo clippy` and `cargo fmt` before PRs\n\n**Development Workflow**:\n```bash\n# Setup\ngit checkout -b feature/my-feature\nbd import -i .beads/issues.jsonl\n\n# Development cycle\ncargo build --lib\ncargo test --lib\ncargo clippy\n\n# E2E testing\nbash tests/e2e/relevant_test.sh\n\n# Commit\ngit add . \u0026\u0026 git commit -m \"Descriptive message\"\n\n# Before PR\ncargo fmt\ncargo clippy --all-targets\ncargo test --all\n\n# Export Beads state\nbd export -o .beads/issues.jsonl\n```\n\n---\n\n## License\n\nSee LICENSE file for details.\n\n---\n\n## Status\n\n**Current Version**: 2.3.1\n\n**v2.4.0 Release (2025-11-23)** - Distributed Coordination:\n- ✅ **Peer Discovery**: Iroh-based P2P discovery and connection management\n- ✅ **Work Delegation**: Distributed task execution across connected peers\n- ✅ **Network Visualization**: TUI-based network graph and status monitoring\n- ✅ **Documentation**: Updated guides for distributed setup and usage\n\n**v2.3.1 Release (2025-11-09)** - Dashboard Crash Fix:\n- ✅ **Critical Bug Fix**: Fixed dashboard crash from NaN values in health metrics\n- ✅ **Terminal Corruption Prevention**: Added panic handler to restore terminal state\n- ✅ **Floating-Point Safety**: Fixed unsafe `partial_cmp().unwrap()` patterns\n- ✅ **Enhanced Error Handling**: SSE bounds checking, graceful error recovery\n- ✅ **Comprehensive Tests**: 11 sparkline tests + 8 anaphora tests passing\n- ✅ **Documentation**: Troubleshooting guide + development best practices\n\n**v2.3.0 Release (2025-11-08)** - Dashboard Redesign \u0026 CLI Operations Tracking:\n- ✅ **Dashboard Redesign**: 4-panel layout replacing 7-panel \"wall of garbage\"\n  - System Overview (top): At-a-glance health metrics\n  - Activity Stream (left, 60%): Intelligent event log with filtering\n  - Agent Details (right-top, 40%): Per-agent status and work queues\n  - Operations (right-bottom, 40%): CLI command history with outcomes\n- ✅ **Smart Event Filtering**: 8 categories, compound AND/OR/NOT logic, filter presets\n- ✅ **Event Correlation Engine**: Links start→complete events, duration tracking, slow operation detection\n- ✅ **CLI Operations Tracking**: Real-time CLI command visibility in dashboard\n- ✅ **Full Keyboard Control**: Interactive navigation (q/Esc, 0-3 panel toggles, c to clear)\n- ✅ **Production Quality**: 124+ tests, 6,122 lines of code, comprehensive error handling\n- ✅ **Documentation**: `docs/DASHBOARD.md` (300+ lines) with architecture, features, troubleshooting\n\n**v2.2.0 Release (2025-11-08)** - gRPC Remote Access:\n- ✅ **gRPC Server**: Production-ready gRPC server for remote memory access\n- ✅ **MemoryService**: 13 RPC methods (CRUD, search, streaming operations)\n- ✅ **HealthService**: System monitoring, metrics, statistics\n- ✅ **Language-Agnostic**: Protocol buffer API for Rust, Python, Go, TypeScript, etc.\n- ✅ **Feature-Gated**: Optional `rpc` feature, no impact on default builds\n- ✅ **Test Suite**: 11 RPC integration tests passing, 728 library tests passing\n- ✅ **Documentation**: 1,868 lines of comprehensive RPC documentation\n\n**v2.1.2 Release (2025-11-06)** - Clean Build \u0026 Repository Cleanup:\n- ✅ **Clean Build**: Fixed all 6 compiler warnings (unused variables, imports, fields)\n- ✅ **Repository Cleanup**: Removed temporary files (.bak, .DS_Store) and stale branches\n- ✅ **Documentation Updates**: Updated ROADMAP, README, CHANGELOG for v2.1.2\n- ✅ **Test Suite**: 715 unit tests passing, 0 failures\n- ✅ **Build**: 0 warnings, 0 errors\n\n**v2.1.1 Release (2025-11-06)** - Python Bridge Architecture \u0026 Production Hardening:\n- ✅ **Python Bridge Complete**: PyO3 integration with Claude SDK agents\n- ✅ **Phase 5 Production Hardening**: 8/8 tasks complete (100%)\n  - Structured logging, enhanced errors, validation, metrics\n  - E2E validation with actual Claude API calls (5/5 tests passing)\n  - Comprehensive troubleshooting guide (628 lines)\n- ✅ **Test Suite**: 715 unit tests + 10 integration/E2E tests passing\n- ✅ **Documentation**: 2,200+ lines across 5 major documents\n- ✅ **Clean Build**: 0 warnings, 0 errors\n- ✅ **Stability Fixes**: File descriptor leak prevention, robust process management\n- ✅ **Production-ready**: Fully validated with actual Claude API calls\n\n**Completed (v2.1.0)**:\n- ✅ Core storage and memory system with LibSQL vector search\n- ✅ Multi-agent orchestration (Ractor-based 4-agent system)\n- ✅ **LLM-Enhanced Reviewer** with requirement extraction and semantic validation\n- ✅ Evolution system (consolidation, importance, archival)\n- ✅ Evaluation system (privacy-preserving online learning)\n- ✅ **ICS Standalone Binary** (`mnemosyne-ics`) with template system\n- ✅ **3-Tier Semantic Highlighting** (Structural/Relational/Analytical, 7,500+ lines)\n- ✅ **HTTP API Server** (`:3000`) with SSE event streaming\n- ✅ **Real-time Monitoring Dashboard** (`mnemosyne-dash`)\n- ✅ **Composable Tools Architecture** (Unix philosophy, zero conflicts)\n- ✅ **Event Bridging** (orchestration events → SSE → dashboard)\n- ✅ TUI wrapper mode (deprecated, use composable tools)\n- ✅ CLI commands (remember, recall, evolve, orchestrate, ics, tui)\n- ✅ Installation/uninstallation scripts\n- ✅ Read-only database support\n- ✅ **715 tests passing** (up from 474, +241 new tests)\n- ✅ MCP server integration\n- ✅ **11 new documentation files** (5,000+ lines)\n\n**Known Issues (v2.3.1)**:\n- ⚠️ PyO3 0.22.6 doesn't support Python 3.14+ (use Python 3.9-3.13)\n- ⚠️ Tier 3 LLM integration is scaffolding only (not fully functional)\n\n**Roadmap** (post-v2.3.1):\n- ⏳ Tier 3 LLM integration completion\n- ⏳ Incremental semantic analysis scheduling\n- ⏳ ICS-semantic highlighter integration\n- ⏳ Performance benchmarks for semantic highlighting\n- ⏳ Advanced observability and metrics\n- ⏳ Dynamic agent scaling\n- ⏳ Distributed orchestration\n- ⏳ WebAssembly deployment target\n\n---\n\nFor detailed technical documentation, see [ARCHITECTURE.md](ARCHITECTURE.md).\nFor troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).\nFor MCP server integration, see [MCP_SERVER.md](MCP_SERVER.md).\nFor development progress, see [TODO_TRACKING.md](TODO_TRACKING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frand%2Fmnemosyne","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frand%2Fmnemosyne","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frand%2Fmnemosyne/lists"}