{"id":33409238,"url":"https://github.com/mrtozner/omnimemory","last_synced_at":"2026-05-15T02:03:04.195Z","repository":{"id":325316543,"uuid":"1097507103","full_name":"mrtozner/omnimemory","owner":"mrtozner","description":"13 production microservices that prevent wasteful AI API calls through semantic search, caching, and team learning - 85% cost reduction","archived":false,"fork":false,"pushed_at":"2025-11-20T18:23:33.000Z","size":2490,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-20T18:24:03.299Z","etag":null,"topics":["ai","caching","compression","context-optimization","cost-savings","embeddings","llm","microservices","postgresql","qdrant","redis","semantic-search","token-reduction","vector-search"],"latest_commit_sha":null,"homepage":"","language":"Python","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/mrtozner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"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-11-16T10:13:30.000Z","updated_at":"2025-11-20T18:23:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mrtozner/omnimemory","commit_stats":null,"previous_names":["mrtozner/omnimemory"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mrtozner/omnimemory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrtozner%2Fomnimemory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrtozner%2Fomnimemory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrtozner%2Fomnimemory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrtozner%2Fomnimemory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrtozner","download_url":"https://codeload.github.com/mrtozner/omnimemory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrtozner%2Fomnimemory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285996059,"owners_count":27267669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-23T02:00:06.149Z","response_time":135,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai","caching","compression","context-optimization","cost-savings","embeddings","llm","microservices","postgresql","qdrant","redis","semantic-search","token-reduction","vector-search"],"created_at":"2025-11-23T18:10:59.118Z","updated_at":"2026-05-15T02:03:04.168Z","avatar_url":"https://github.com/mrtozner.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# OmniMemory\n\n**Production-Ready Microservices for Intelligent Context Management**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![Microservices](https://img.shields.io/badge/microservices-13-orange.svg)](#services)\n[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple.svg)](mcp_server/README.md)\n[![MCP Tools](https://img.shields.io/badge/MCP%20tools-25+-purple.svg)](#-new-features-v20)\n[![AI Tools](https://img.shields.io/badge/AI%20tools-Claude%20%7C%20Cursor%20%7C%20Copilot%20%7C%20VS%20Code-green.svg)](#-mcp-integration-architecture-universal-memory-layer)\n[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue.svg)](https://github.com/mrtozner/omnimemory)\n[![Stars](https://img.shields.io/github/stars/mrtozner/omnimemory?style=social)](https://github.com/mrtozner/omnimemory)\n[![Last Commit](https://img.shields.io/github/last-commit/mrtozner/omnimemory)](https://github.com/mrtozner/omnimemory/commits/main)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/mrtozner/omnimemory/pulls)\n\n**[Quick Start](QUICK_START.md)** • **[Services](#services)** • **[Report Issue](https://github.com/mrtozner/omnimemory/issues)**\n\n---\n\n### 🎯 Stop paying for irrelevant files sent to AI APIs\n\n13 production-ready microservices that prevent wasteful API calls through semantic search, smart caching, and team learning—saving 85% on AI development costs.\n\n**NEW in v2.0**: Universal AI tool support (Claude, Cursor, Copilot, VS Code), predictive context loading, workflow pattern mining, auto-generated project docs, and sleep-inspired memory consolidation.\n\n**One-command setup**: `omni init --tool all` automatically configures your AI tools!\n\n\u003c/div\u003e\n\n---\n\n## ⚠️ Setup Complexity\n\n\u003e **OmniMemory consists of 13 independent microservices** that must be started individually\n\u003e\n\u003e - ✅ Each service is production-ready and battle-tested\n\u003e - ⚠️ No unified launcher (manual setup required)\n\u003e - ⚠️ Services must be started in dependency order\n\u003e - ℹ️ **Recommended for**: Advanced users, custom integrations\n\u003e - 💡 **Looking for simple deployment?** See [Omn1-ACE](https://github.com/mrtozner/omn1-ace) (integrated system)\n\n**[📖 Step-by-Step Setup Guide →](QUICK_START.md)**\n\n---\n\n## 💡 Why OmniMemory?\n\n**The Core Problem**: AI coding assistants send 50+ files to expensive APIs when only 3 are relevant—wasting 85% of your API budget.\n\n### How OmniMemory Solves This\n\n| Without OmniMemory | With OmniMemory | Savings |\n|-------------------|-----------------|---------|\n| Send all 50 files → API | Semantic search finds 3 relevant (local, free) | 80% |\n| Re-send everything | Cache check: 2 already sent, skip them (local, free) | 13% |\n| Send raw files | Compress remaining file (optional) | 5% |\n| **60,000 tokens** | **950 tokens** | **98.5%** |\n| **$0.90 per query** | **$0.014 per query** | **$0.886 saved** |\n\n### Real-World Impact\n\n| Feature | Traditional Approach | OmniMemory Microservices |\n|---------|---------------------|--------------------------|\n| **Files Sent to API** | All 50 files that match keyword | Only 3 semantically relevant files |\n| **Redundancy Prevention** | Re-send everything every query | L1/L2/L3 cache skips already sent files |\n| **Token Usage** | 60,000 tokens (includes irrelevant) | 950 tokens (only relevant) |\n| **API Cost** | $0.90 per query | $0.014 per query |\n| **Monthly Cost** (500 queries) | $450 | $68 |\n| **Team Benefit** | Each user sends full context | L2 cache shares across team |\n| **Architecture** | Monolithic | 13 modular services |\n\n**Key Insight**: 85% of savings comes from NOT SENDING irrelevant files in the first place.\n\n---\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────────────┐\n│         Client Applications                 │\n│  (Claude Code, Cursor, Continue, etc.)      │\n└──────────────┬──────────────────────────────┘\n               │\n        ┌──────▼──────┐\n        │  MCP Server │ ← Intercepts before API call\n        └──────┬──────┘\n               │\n    ┌──────────┼──────────┐\n    │          │          │\n┌───▼───┐  ┌──▼──┐   ┌──▼────┐\n│Embed  │  │Search│   │Cache │\n│Layer  │  │Layer│   │Layer  │  ← All LOCAL (no API cost)\n└───┬───┘  └──┬──┘   └──┬────┘\n    │         │         │\n    │   Find 3 of 50   Skip 2\n    │   relevant files already sent\n    │         │         │\n    └─────────┼─────────┘\n              │\n         ┌────▼────┐\n         │  Send   │ ← Only 1 file (950 tokens)\n         │  to API │    Instead of 50 (60K tokens)\n         └─────────┘\n\nResult: $0.014 instead of $0.90 per query\n```\n\n---\n\n## 🎉 New Features (v2.0)\n\n**OmniMemory 2.0** transforms the system from a storage layer into an **intelligent memory system** with learning capabilities, predictive context loading, and universal AI tool compatibility.\n\n### 🌐 MCP Integration Architecture (Universal Memory Layer)\n\nTransform OmniMemory into a universal memory layer that works across **all AI coding tools** — not just Claude.\n\n**Key Capabilities:**\n- **Universal Compatibility**: Works with Claude Code, Cursor, GitHub Copilot, VS Code extensions\n- **Memory Passport**: Export/import sessions across different AI tools seamlessly\n- **25+ MCP Tools**: Organized into 5 categories (Memory, Search, Session, Workflow, Utility)\n- **Cross-Tool Sessions**: Start in Claude, continue in Cursor without losing context\n- **OpenAPI Specification**: Standardized API for easy integration\n\n**Quick Usage:**\n```typescript\n// Export session from Claude\nawait mcp.call_tool(\"omn_export_session\");\n// Generates portable Memory Passport JSON\n\n// Import in Cursor\nawait mcp.call_tool(\"omn_restore_session\", {\n  passport: \"\u003cpassport_json\u003e\",\n  tool_id: \"cursor\"\n});\n// Full context restored in \u003c2 seconds!\n```\n\n**[📖 Full Documentation](MCP_INTEGRATION_ARCHITECTURE.md)** • **[OpenAPI Spec](mcp_server/MCP_TOOLS_OPENAPI.yaml)**\n\n---\n\n### 📚 Memory Bank (Auto-Generated Project Context)\n\nAutomatically generates structured project documentation from your development sessions — no manual effort required.\n\n**Key Capabilities:**\n- **Auto-Generated Docs**: Creates prd.md, design.md, tasks.md, context.md, patterns.md from session history\n- **GitHub Copilot Integration**: Exports to `.github/copilot-instructions.md` for instant Copilot context\n- **Session Mining**: Extracts product requirements, architecture decisions, and coding patterns\n- **Zero Maintenance**: Updates automatically as you work\n- **Universal Format**: Works with any AI tool that reads markdown\n\n**Quick Usage:**\n```bash\n# CLI approach\nomni-init memory-bank --workspace /path/to/project\n\n# MCP tool approach (from any AI tool)\nawait mcp.call_tool(\"generate_memory_bank\", {\n  workspace_path: \"/path/to/project\"\n});\n\n# Result: /memory-bank/ directory with 5 structured docs\n# • prd.md - Product requirements\n# • design.md - Architecture, DB schema, APIs\n# • tasks.md - Development tasks and progress\n# • context.md - Recent session updates\n# • patterns.md - Coding conventions learned\n```\n\n**Benefits:**\n- New team members get instant project context\n- AI tools understand your project conventions\n- No manual documentation writing\n- Copilot gives better suggestions with project context\n\n**[📖 Implementation](mcp_server/memory_bank_manager.py)**\n\n---\n\n### 🔮 Predictive Context Preloader (ProContext)\n\nMachine learning engine that **predicts what code you'll need next** and pre-loads it before you ask — making your AI assistant feel psychic.\n\n**Key Capabilities:**\n- **ML-Based Prediction**: Combines 4 predictor types (Markov chain, co-occurrence, temporal, workflow)\n- **Pre-Warming**: Loads predicted context into cache before you request it\n- **6-17% Productivity Gain**: Measured reduction in time waiting for context\n- **Confidence Scores**: See how certain the system is about predictions\n- **Learns Your Patterns**: Gets smarter the more you use it\n\n**Quick Usage:**\n```typescript\n// Get predicted context for current task\nconst predictions = await mcp.call_tool(\"get_predicted_context\", {\n  current_files: [\"src/auth.ts\"],\n  recent_actions: [\"read\", \"search\"],\n  limit: 5\n});\n\n// Returns:\n// [\n//   { file: \"src/middleware/auth.ts\", confidence: 0.89, reason: \"high_cooccurrence\" },\n//   { file: \"src/utils/jwt.ts\", confidence: 0.76, reason: \"workflow_pattern\" },\n//   ...\n// ]\n\n// Train predictor on current session (automatic in background)\nawait mcp.call_tool(\"train_predictor\");\n```\n\n**How It Works:**\n1. **Markov Chain**: \"After editing auth.ts, users typically edit middleware/auth.ts\"\n2. **Co-occurrence**: \"Files A and B are often worked on together\"\n3. **Temporal**: \"Between 9-11am, you usually work on frontend files\"\n4. **Workflow**: \"Bug fix workflows usually involve tests → implementation → docs\"\n\n**[📖 Implementation](mcp_server/predictive_preloader.py)**\n\n---\n\n### 🔄 Workflow Pattern Miner (WorkflowGPT)\n\nAutomatically discovers recurring workflow patterns and suggests next steps — like autocomplete for your development process.\n\n**Key Capabilities:**\n- **Automatic Pattern Discovery**: Uses PrefixSpan algorithm to find recurring sequences\n- **Workflow Suggestions**: \"You usually run tests after editing this file type\"\n- **Automation Creation**: Convert patterns into executable automations\n- **22% Productivity Increase**: From workflow automation alone\n- **Confidence Scoring**: See how reliable each suggestion is\n- **7 MCP Tools**: discover_patterns, suggest_workflow, create_automation, and more\n\n**Quick Usage:**\n```typescript\n// Discover patterns from session history\nconst patterns = await mcp.call_tool(\"discover_patterns\", {\n  min_frequency: 3,\n  min_confidence: 0.7\n});\n\n// Returns:\n// [\n//   {\n//     pattern_id: \"test_after_impl\",\n//     sequence: [\"file_edit:.ts\", \"command:npm\", \"file_read:.test.ts\"],\n//     frequency: 47,\n//     success_rate: 0.94,\n//     confidence: 0.89\n//   }\n// ]\n\n// Get suggestions for current context\nconst suggestions = await mcp.call_tool(\"suggest_workflow\", {\n  current_sequence: [\"file_edit:auth.ts\"]\n});\n// → \"You typically run `npm test` next (confidence: 0.87)\"\n\n// Create automation from pattern\nawait mcp.call_tool(\"create_automation\", {\n  pattern_id: \"test_after_impl\",\n  name: \"Auto-test after TypeScript edits\"\n});\n```\n\n**Example Patterns Discovered:**\n- \"Edit → Lint → Commit\" (detected in 89% of successful commits)\n- \"Bug Report → Read Tests → Read Implementation → Edit → Test\" (typical debugging flow)\n- \"Search → Read → Edit → Write Test\" (feature implementation pattern)\n\n**[📖 Implementation](mcp_server/workflow_pattern_miner.py)**\n\n---\n\n### 🗜️ Advanced Memory Compression (CompactMemory)\n\nLLMLingua-2 inspired compression achieves **3-4x memory storage improvement** while preserving semantic accuracy.\n\n**Key Capabilities:**\n- **Token-Level Compression**: LLMLingua-2 style perplexity-based token pruning\n- **4-Tier Hierarchical Storage**:\n  - **Recent** (0-7 days): Full detail, no compression\n  - **Active** (7-30 days): 2x compression (light)\n  - **Working** (30-90 days): 3x compression (medium)\n  - **Archived** (90+ days): 4x compression or embedding-only (95% reduction)\n- **Semantic Preservation**: 95%+ accuracy maintained after compression\n- **Automatic Aging**: Memories automatically move through tiers\n- **6 MCP Tools**: compress_memory, compress_conversation, decompress, and more\n\n**Quick Usage:**\n```typescript\n// Compress a long conversation\nconst result = await mcp.call_tool(\"compress_conversation\", {\n  conversation_id: \"sess_abc123\",\n  target_ratio: 0.25  // 4x compression\n});\n\n// Returns:\n// {\n//   original_tokens: 12000,\n//   compressed_tokens: 3000,\n//   compression_ratio: 4.0,\n//   semantic_preservation: 0.96,\n//   important_phrases_preserved: [\"JWT authentication\", \"database schema\", ...]\n// }\n\n// Compress specific memory\nawait mcp.call_tool(\"compress_memory\", {\n  memory_id: \"mem_xyz\",\n  level: \"medium\"  // 3x compression\n});\n\n// Decompress when needed\nconst decompressed = await mcp.call_tool(\"decompress_memory\", {\n  memory_id: \"mem_xyz\"\n});\n```\n\n**Compression Techniques:**\n1. **Token Pruning**: Remove low-perplexity tokens (articles, conjunctions)\n2. **Phrase Preservation**: Keep important technical terms intact\n3. **Hierarchical Summarization**: Progressive detail reduction\n4. **Embedding Fallback**: Store only vector for very old memories\n\n**Storage Savings:**\n- 1,000 conversations @ 10K tokens each = 10M tokens\n- After compression: 2.5M tokens (75% reduction)\n- Embedding-only archival: 500K tokens (95% reduction)\n\n**[📖 Implementation](mcp_server/advanced_compressor.py)**\n\n---\n\n### 😴 Sleep-Inspired Memory Consolidation\n\nBackground consolidation engine that mimics human sleep to reduce **catastrophic forgetting by 52%** (research-backed).\n\n**Key Capabilities:**\n- **4-Phase Sleep Cycle**:\n  1. **Replay** (REM sleep): Replay recent memories and identify patterns\n  2. **Strengthen** (slow-wave sleep): Reinforce important memories\n  3. **Prune** (synaptic homeostasis): Archive/delete low-value memories\n  4. **Synthesize**: Discover cross-session insights and meta-learnings\n- **Idle Period Activation**: Runs during development pauses (\u003e15 min idle)\n- **52% Forgetting Reduction**: Based on neuroscience research on memory consolidation\n- **Insight Discovery**: Finds patterns across multiple sessions\n- **4 MCP Tools**: trigger_consolidation, get_status, get_stats, get_insights\n\n**Quick Usage:**\n```typescript\n// Manual trigger (normally runs automatically during idle)\nawait mcp.call_tool(\"trigger_consolidation\", {\n  min_idle_minutes: 15\n});\n\n// Check consolidation status\nconst status = await mcp.call_tool(\"get_consolidation_status\");\n// Returns:\n// {\n//   phase: \"strengthen\",\n//   progress: 0.62,\n//   memories_processed: 847,\n//   estimated_completion_minutes: 3\n// }\n\n// Get consolidation statistics\nconst stats = await mcp.call_tool(\"get_consolidation_stats\");\n// Returns:\n// {\n//   total_cycles: 23,\n//   memories_archived: 1547,\n//   memories_deleted: 89,\n//   avg_consolidation_efficiency: 0.87,\n//   catastrophic_forgetting_reduction: 0.52\n// }\n\n// Retrieve discovered insights\nconst insights = await mcp.call_tool(\"get_consolidation_insights\", {\n  limit: 10\n});\n// Returns cross-session patterns like:\n// \"You always implement authentication with JWT + Redis sessions\"\n// \"Database migrations typically require 3 files: migration, model, test\"\n```\n\n**How It Works:**\n1. **Memory Replay**: Re-activate recent memories to identify patterns\n2. **Pattern Strengthening**: Increase importance scores for recurring patterns\n3. **Memory Pruning**: Archive memories with low importance scores\n4. **Cross-Session Synthesis**: Find common patterns across sessions\n\n**Benefits:**\n- **Better Long-Term Retention**: Important patterns remembered longer\n- **Reduced Memory Bloat**: Automatic cleanup of low-value memories\n- **Insight Discovery**: Surface patterns you didn't consciously notice\n- **No Manual Maintenance**: Runs automatically in background\n\n**[📖 Implementation](mcp_server/sleep_consolidation.py)**\n\n---\n\n## 🚀 Quick Start with New Features\n\n### 1. Enable Universal AI Tool Support\n\n```bash\n# Configure for your AI tool\ncd omnimemory-init-cli\npip install -e .\n\n# Auto-configure (Claude, Cursor, VS Code, etc.)\nomni init --tool all\n\n# The init tool will:\n# ✅ Detect installed AI tools\n# ✅ Configure MCP servers\n# ✅ Inject custom prompts\n# ✅ Enable all 25+ MCP tools\n```\n\n### 2. Generate Memory Bank Documentation\n\n```bash\n# Auto-generate project docs from session history\nomni-init memory-bank --workspace /path/to/your/project\n\n# Or use MCP tool from any AI assistant:\n# \"Generate a memory bank for this project\"\n\n# Result: /memory-bank/ directory with:\n# • prd.md, design.md, tasks.md, context.md, patterns.md\n# • .github/copilot-instructions.md (for Copilot)\n```\n\n### 3. Enable Predictive Context \u0026 Workflow Mining\n\n```typescript\n// From your AI tool, these work automatically:\n\n// Get predicted next files\n\"What files will I likely need for this task?\"\n// → Uses ProContext ML predictions\n\n// Get workflow suggestions\n\"What should I do next after editing this file?\"\n// → Uses WorkflowGPT pattern mining\n\n// The system learns your patterns automatically\n// No configuration needed!\n```\n\n### 4. Cross-Tool Session Migration\n\n```bash\n# In Claude:\n\"Export my current session as a Memory Passport\"\n# → Generates portable JSON\n\n# In Cursor (or any other tool):\n\"Restore session from this passport: \u003cpaste JSON\u003e\"\n# → Full context restored in \u003c2 seconds\n```\n\n### 5. Monitor Advanced Features\n\n```bash\n# Check consolidation status\ncurl http://localhost:8003/consolidation/status\n\n# View compression stats\ncurl http://localhost:8003/compression/stats\n\n# See workflow patterns discovered\ncurl http://localhost:8003/workflows/patterns\n```\n\n**[📖 Complete Setup Guide](QUICK_START.md)**\n\n---\n\n## 🚀 Services\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### Core Services (Prevent Wasteful API Calls)\n\n**omnimemory-embeddings** (Port 8000)\n- **Purpose**: Enable semantic search to find relevant files\n- Vector embedding generation for text and code\n- Multiple models supported (sentence-transformers)\n- **Impact**: Foundation for 80% savings\n- [Documentation](omnimemory-embeddings/README.md)\n\n**omnimemory-storage**\n- **Purpose**: Store embeddings for fast retrieval\n- Qdrant integration (vector database)\n- PostgreSQL for relational data\n- **Impact**: \u003c100ms semantic search\n- [Documentation](omnimemory-storage/README.md)\n\n**omnimemory-redis-cache**\n- **Purpose**: Prevent re-sending files to API\n- 3-tier caching (L1: user, L2: team, L3: archive)\n- LRU eviction with priorities\n- **Impact**: 13% additional savings\n- [Documentation](omnimemory-redis-cache/README.md)\n\n**omnimemory-knowledge-graph**\n- **Purpose**: Understand code structure for better retrieval\n- AST analysis and dependency tracking\n- NetworkX graph algorithms\n- **Impact**: Improves search relevance\n- [Documentation](omnimemory-knowledge-graph/README.md)\n\n**omnimemory-file-context**\n- **Purpose**: Intelligent file chunking and relevance scoring\n- Context extraction\n- **Impact**: Better semantic matches\n- [Documentation](omnimemory-file-context/README.md)\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### Secondary Optimization Services\n\n**omnimemory-compression** (Port 8001)\n- **Purpose**: Further reduce size of files that DO get sent\n- Code-aware compression (85-94% reduction)\n- Multi-language support\n- **Impact**: 5% additional savings (after retrieval)\n- [Documentation](omnimemory-compression/README.md)\n\n**omnimemory-procedural**\n- **Purpose**: Learn workflow patterns for prefetching\n- Session pattern recognition\n- Context prediction\n- **Impact**: Faster responses\n- [Documentation](omnimemory-procedural/README.md)\n\n**omnimemory-agent-memory**\n- **Purpose**: Conversation tracking\n- Memory persistence\n- Agent context management\n- [Documentation](omnimemory-agent-memory/README.md)\n\n### Monitoring \u0026 Metrics\n\n**omnimemory-metrics-service** (Port 8004)\n- Token usage tracking\n- Performance monitoring\n- Real-time dashboards\n- [Documentation](omnimemory-metrics-service/README.md)\n\n**omnimemory-multi-dashboard** (Port 3000)\n- Web-based monitoring\n- Team analytics\n- [Documentation](omnimemory-multi-dashboard/README.md)\n\n### Client Tools\n\n**mcp_server**\n- Claude Code integration via MCP\n- [Documentation](mcp_server/README.md)\n\n**omnimemory-cli**\n- Service management and testing\n- [Documentation](omnimemory-cli/README.md)\n\n**omnimemory-evaluation**\n- Benchmarking and quality assessment\n- [Documentation](omnimemory-evaluation/README.md)\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 📊 Benchmarks \u0026 Performance\n\n### Token Reduction Results (Real Production Scenarios)\n\n| Scenario | Files Found | Files Sent | Tokens (Baseline) | Tokens (OmniMemory) | Reduction % | Cost Saved |\n|----------|-------------|------------|-------------------|---------------------|-------------|------------|\n| Auth Implementation | 50 | 3 (2 cached) | 2,847 | 275 | **90.3%** | $0.0179 |\n| Bug Debugging | 35 | 2 (1 cached) | 1,932 | 466 | **75.9%** | $0.0026 |\n| Payment Refactoring | 80 | 5 (3 cached) | 3,156 | 600 | **81.0%** | $0.0043 |\n| Performance Optimization | 45 | 2 (1 cached) | 2,844 | 575 | **79.8%** | $0.0048 |\n| Stripe Integration | 60 | 4 (3 cached) | 3,000 | 579 | **80.7%** | $0.0054 |\n| **Average** | **54** | **3.2** | **13,779** | **2,099** | **84.8%** | **$0.035** |\n\n### How Savings Break Down\n\n| Optimization | Mechanism | Tokens Prevented | % of Savings |\n|--------------|-----------|------------------|--------------|\n| **Semantic Search** | Find 3 relevant of 50 files | ~47,000 | 80% |\n| **Cache Hits (L1/L2/L3)** | Skip files already sent | ~8,000 | 13% |\n| **Compression** | Reduce size of remaining files | ~3,000 | 5% |\n| **Context Pruning** | Trim conversation history | ~1,050 | 2% |\n\n**Key Insight**: 80% of savings is from semantic search preventing irrelevant files from hitting the API.\n\n**[📈 Full Benchmark Report →](benchmarks/TOKEN_EFFICIENCY_README.md)**\n\n### Performance Metrics\n\n| Operation | Time | Cost | Impact |\n|-----------|------|------|--------|\n| **Semantic search** | \u003c100ms | $0 (local) | Find relevant files |\n| **Cache lookup** | \u003c5ms | $0 (local) | Skip already sent |\n| **Embedding generation** | \u003c50ms | $0 (local) | Enable search |\n| **Compression** | \u003c200ms | $0 (local) | Secondary optimization |\n| **API call (prevented)** | N/A | **$0.90 saved** | Main value |\n| **API call (optimized)** | 1-3s | $0.014 | 98.5% reduction |\n\n---\n\n## 🎯 Quick Start\n\n### Prerequisites\n\n- Python 3.9+\n- Node.js 16+ (for dashboard)\n- Docker \u0026 Docker Compose (for infrastructure)\n\n### 🐳 Docker Infrastructure (Recommended)\n\nStart infrastructure services (PostgreSQL, Redis, Qdrant) using convenience scripts:\n\n```bash\n# Clone the repository\ngit clone https://github.com/mrtozner/omnimemory.git\ncd omnimemory\n\n# Start infrastructure services (auto-creates .env from template)\n./start.sh\n\n# Check service status\n./status.sh\n\n# View logs\n./logs.sh           # All services\n./logs.sh postgres  # Specific service\n\n# Restart services\n./restart.sh\n\n# Stop services\n./stop.sh\n```\n\n**Available scripts:**\n- `start.sh` - Start Docker infrastructure only (PostgreSQL, Redis, Qdrant)\n- `stop.sh` - Stop Docker infrastructure only\n- `restart.sh` - Restart infrastructure\n- `logs.sh` - View service logs (all or specific service)\n- `status.sh` - Check infrastructure health\n\n**Note**: These scripts start infrastructure only. For full system launch (infrastructure + microservices), use `./launch.sh` (see below).\n\n**Manual Docker commands** (if you prefer):\n```bash\ncp .env.example .env \u0026\u0026 nano .env\ndocker-compose up -d\ncurl http://localhost:6333  # Qdrant\n```\n\n### 🚀 Full System Launch (All Services)\n\nStart everything with one command:\n\n```bash\n# Launch infrastructure + all microservices\n./launch.sh\n\n# Check status of all services\n./status-all.sh\n\n# Stop everything\n./stop-all.sh\n```\n\n**What it does:**\n- Starts Docker infrastructure (PostgreSQL, Redis, Qdrant)\n- Launches Python microservices (Embeddings, Compression, Procedural, Metrics)\n- Tracks processes in `~/.omnimemory/pids`\n- Logs to `~/.omnimemory/logs/`\n- Validates health of all services\n\n**Available commands:**\n- `./launch.sh` - Start all services (infrastructure + microservices)\n- `./status-all.sh` - Check comprehensive status with health checks\n- `./stop-all.sh` - Stop all services including microservices\n\n**Requirements:**\n- Python dependencies installed in each service directory\n- Docker infrastructure running (auto-started by launch.sh)\n\n**Useful commands:**\n```bash\n# View all logs\ntail -f ~/.omnimemory/logs/*.log\n\n# View specific service log\ntail -f ~/.omnimemory/logs/omnimemory-embeddings.log\n\n# Check what's running\n./status-all.sh\n```\n\n### 📦 Individual Services\n\nEach service can be run independently:\n\n```bash\n# Example: Embeddings service (enables semantic search)\ncd omnimemory-embeddings\npip install -r requirements.txt\npython -m src.embedding_server\n\n# Example: Redis cache service (prevents re-sending)\ncd omnimemory-redis-cache\npip install -r requirements.txt\npython -m src.cache_server\n```\n\n**[📖 Detailed Setup Instructions →](QUICK_START.md)**\n\n---\n\n## 🎯 Automatic AI Tool Configuration\n\n**NEW**: Use `omni init` to automatically configure your AI tools with OmniMemory!\n\n### Quick Setup (One Command)\n\n```bash\n# Install the init CLI\ncd omnimemory-init-cli\npip install -e .\n\n# Auto-configure your AI tool\nomni init --tool claude    # For Claude Code\nomni init --tool cursor    # For Cursor\nomni init --tool all       # Configure all detected tools\n```\n\n**What it does:**\n1. ✅ Detects installed AI tools (Claude Code, Cursor, VSCode, Windsurf, etc.)\n2. ✅ Configures MCP servers with correct tool IDs\n3. ✅ **Auto-injects custom prompts** that instruct AI to use OmniMemory tools\n4. ✅ Creates backup of existing configs before modifying\n\n**Supported Tools:**\n- Claude Code (`~/.claude/CLAUDE.md`)\n- Cursor (`~/.cursorrules`)\n- Windsurf (`~/.windsurfrules`)\n- VS Code + Cline/Continue/Aider\n- Gemini Code Assist, Codex, Cody\n\n**Result**: Your AI tool will automatically use OmniMemory's compressed reading and semantic search instead of sending 50 files to expensive APIs.\n\n**[📖 Full Init CLI Documentation →](omnimemory-init-cli/README.md)**\n\n---\n\n## ⚠️ Model Compatibility \u0026 Team Considerations\n\n### Embedding Model Consistency (Critical for Teams)\n\n**All team members MUST use the same embedding model** for L2 cache sharing:\n\n| Model | Dimensions | Speed | Quality | Use Case |\n|-------|-----------|-------|---------|----------|\n| **all-MiniLM-L6-v2** (default) | 768 | Fast | Good | General purpose |\n| **all-mpnet-base-v2** | 768 | Medium | Better | High quality needed |\n| **text-embedding-3-small** | 1536 | Fast | Best | Enterprise (API key req) |\n\n**Why this matters**:\n- Different embedding models = different vectors = incompatible semantic search\n- Team L2 cache requires consistent embeddings\n- Mixing models breaks cache sharing = wasteful API calls return\n\n### Context Window Configuration\n\nConfigure for your target AI model:\n\n| Model | Context Window | Configuration |\n|-------|---------------|---------------|\n| Claude 3.5 Sonnet | 200K tokens | `TARGET_MODEL=claude CONTEXT_WINDOW_SIZE=200000` |\n| GPT-4 Turbo | 128K tokens | `TARGET_MODEL=gpt CONTEXT_WINDOW_SIZE=128000` |\n| Gemini 1.5 Pro | 1M tokens | `TARGET_MODEL=gemini CONTEXT_WINDOW_SIZE=1000000` |\n| GPT-3.5 Turbo | 16K tokens | `TARGET_MODEL=gpt35 CONTEXT_WINDOW_SIZE=16000` |\n\n### Team Best Practices\n\n**For consistent team experience**:\n1. ✅ Document your embedding model in team wiki\n2. ✅ Standardize on one target AI model (Claude, GPT, or Gemini)\n3. ✅ Set up L2 cache to share context across team\n4. ✅ Share configuration via `.env.team` file\n\n---\n\n## 🔧 Configuration\n\n### Environment Variables\n\n```bash\n# Core Infrastructure\nPOSTGRES_HOST=localhost\nPOSTGRES_DB=omnimemory\nPOSTGRES_PASSWORD=CHANGE_ME\nREDIS_URL=redis://localhost:6379\nQDRANT_URL=http://localhost:6333\n\n# Embedding Configuration (for semantic search)\nEMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2\nEMBEDDING_CACHE_SIZE=1000\n\n# Compression Configuration (secondary optimization)\nCOMPRESSION_RATIO=0.15  # 85% reduction\nQUALITY_THRESHOLD=0.9\n\n# Cache Configuration (prevents re-sending)\nCACHE_TTL=3600\nREDIS_CACHE_PREFIX=omnimemory\n\n# Microservice URLs\nEMBEDDING_SERVICE_URL=http://localhost:8000\nCOMPRESSION_SERVICE_URL=http://localhost:8001\nMETRICS_SERVICE_URL=http://localhost:8004\n```\n\n**[📋 Complete Configuration Reference →](.env.example)**\n\n---\n\n## 📊 Real-World Example\n\n### Scenario: \"Find the authentication bug in my Node.js app\"\n\n**WITHOUT OmniMemory:**\n```\nAI Tool searches all files:\n→ Finds 50 files mentioning \"auth\"\n→ Sends ALL 50 files → Anthropic API\n  ✓ auth.ts (relevant)\n  ✓ auth-middleware.ts (relevant)\n  ✓ auth.test.ts (relevant)\n  ✗ database-config.ts (irrelevant)\n  ✗ logging-utils.ts (irrelevant)\n  ✗ ...45 more irrelevant files\n\nTokens sent: 60,000\nCost: $0.90\nWaste: 47 files (78%) completely irrelevant\n```\n\n**WITH OmniMemory:**\n```\nStep 1: Semantic Search (LOCAL, FREE)\n→ omnimemory-embeddings: Generate query embedding\n→ omnimemory-storage: Search Qdrant vector DB\n→ Finds 3 relevant files:\n  ✓ auth.ts (similarity: 0.94)\n  ✓ auth-middleware.ts (similarity: 0.89)\n  ✓ auth.test.ts (similarity: 0.86)\n→ Time: 85ms, Cost: $0\n\nStep 2: Cache Check (LOCAL, FREE)\n→ omnimemory-redis-cache: Check L1/L2/L3\n  • auth.ts: In L1 cache (you sent 2 queries ago) → SKIP\n  • auth-middleware.ts: In L2 cache (teammate sent) → SKIP\n  • auth.test.ts: Not cached → SEND\n→ Time: 3ms, Cost: $0\n\nStep 3: Optional Compression (LOCAL, FREE)\n→ omnimemory-compression: Reduce file size\n  • auth.test.ts: 3,000 tokens → 450 tokens (85% reduction)\n→ Time: 120ms, Cost: $0\n\nStep 4: Send to API (PAID)\n→ Only 1 file sent\n→ Tokens: 950 (vs 60,000)\n→ Cost: $0.014 (vs $0.90)\n\nSavings: $0.886 (98.5%)\nHow: 59,050 tokens NEVER HIT the paid API\n```\n\n---\n\n## 🔒 Security\n\n**Before production deployment**:\n\n1. ✅ Change default passwords in `.env`\n2. ✅ Enable authentication on all services\n3. ✅ Use TLS/SSL for service communication\n4. ✅ Configure network policies to restrict access\n5. ✅ Regular security updates for dependencies\n6. ✅ Monitor services for suspicious activity\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes with tests\n4. Run tests: `pytest`\n5. Submit a pull request\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n## 🔗 Related Projects\n\n- **[Omn1-ACE](https://github.com/mrtozner/omn1-ace)**: Integrated deployment (simpler setup, early stage)\n- **Individual service documentation**: See subdirectories\n\n---\n\n## 🙏 Acknowledgments\n\nThis project emerged from extensive research into context optimization for AI development tools. The core insight: 85% of tokens sent to AI APIs are irrelevant—preventing those wasteful API calls is the primary value.\n\n**v2.0** adds intelligent learning capabilities inspired by neuroscience research on memory consolidation, bringing features like predictive context loading, workflow pattern mining, and sleep-inspired memory consolidation.\n\n**Built with:**\n- **Core**: FastAPI, Qdrant, PostgreSQL, Redis, NetworkX, sentence-transformers\n- **v2.0 Features**: LLMLingua-2 (compression), PrefixSpan (pattern mining), Markov chains (prediction), SQLite (metadata)\n- **Research**: Memory consolidation techniques, perplexity-based compression, sequential pattern mining\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[⭐ Star this repo](https://github.com/mrtozner/omnimemory)** if you find it useful!\n\n**[💬 Discussions](https://github.com/mrtozner/omnimemory/discussions)** • **[🐛 Report Bug](https://github.com/mrtozner/omnimemory/issues)** • **[📖 Documentation](QUICK_START.md)**\n\nMade with ❤️ by [Mert Ozoner](https://github.com/mrtozner)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrtozner%2Fomnimemory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrtozner%2Fomnimemory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrtozner%2Fomnimemory/lists"}