diff --git a/integrations/omega-memory/README.md b/integrations/omega-memory/README.md new file mode 100644 index 00000000..4cccc321 --- /dev/null +++ b/integrations/omega-memory/README.md @@ -0,0 +1,136 @@ +# OMEGA — Persistent MCP Memory Server for AI Coding Agents + +> Long-term memory for Claude Code, Cursor, Windsurf, and any MCP-compatible AI coding assistant. Local-first, offline, no API keys required. + +## What It Does + +[OMEGA](https://github.com/omega-memory/omega-memory) is an open-source MCP memory server that gives AI coding agents persistent, semantically searchable memory across sessions. It runs locally on SQLite — your data never leaves your machine. + +Unlike simple key-value memory stores or conversation history workarounds, OMEGA provides: + +- **Semantic search**: Query memories by meaning, not just keywords. Local ONNX embeddings find relevant context even when the wording differs — no API calls, no cloud dependency. +- **Typed memories**: Store decisions, lessons learned, error patterns, user preferences, and session summaries as distinct types with different retention behaviors. +- **Memory decay and consolidation**: Low-value memories fade over time. Important memories are reinforced through access. The memory store stays relevant without manual pruning. +- **Contradiction detection**: When a new memory conflicts with an existing one, OMEGA flags the contradiction so agents don't act on stale information. +- **Cross-session continuity**: Agents pick up exactly where they left off. Checkpoint a task mid-session, resume it days later. +- **Multi-agent coordination**: Memories are scoped by agent type, entity, and project. Multiple agents share a memory store without stepping on each other. + +### Why OMEGA over other memory solutions? + +| | OMEGA | Generic MCP memory | No memory (default) | +|---|---|---|---| +| Semantic search | Local embeddings (ONNX) | Keyword only | N/A | +| Memory types | 6 types with different behaviors | Untyped blobs | N/A | +| Decay/consolidation | Automatic | Manual cleanup | N/A | +| Contradiction detection | Built-in | No | N/A | +| Cross-session resume | Checkpoint/resume API | Manual | Lost on session end | +| Privacy | 100% local, SQLite, offline | Varies | N/A | +| API keys required | None | Varies | N/A | + +## Setup + +### Requirements + +- Python 3.11+ +- Any MCP-compatible client: Claude Code, Cursor, Windsurf, Zed, or any tool supporting the Model Context Protocol + +### Install + +```bash +pip install omega-memory +``` + +Or run the setup script: + +```bash +./integrations/omega-memory/setup.sh +``` + +### Configure Your MCP Client + +Add OMEGA to your MCP client config. For Claude Code (`~/.claude.json`): + +```json +{ + "mcpServers": { + "omega": { + "command": "python3.11", + "args": ["-m", "omega.server.mcp_server"] + } + } +} +``` + +For other clients, adapt the command/args to your MCP config format. + +## Available Tools + +OMEGA exposes these MCP tools: + +| Tool | Description | +|------|-------------| +| `omega_store` | Store a memory with type, metadata, priority, and entity/project scoping | +| `omega_query` | Search memories by semantic similarity, exact phrase, timeline, or browse by type | +| `omega_welcome` | Session greeting with context briefing from recent memories | +| `omega_protocol` | Returns the agent's operating protocol and instructions | +| `omega_profile` | Load or update an entity/project profile | +| `omega_checkpoint` | Save current task state for later resumption | +| `omega_resume_task` | Resume a previously checkpointed task | +| `omega_memory` | Direct memory operations (read, update, delete) | +| `omega_remind` | Set and retrieve reminders | +| `omega_maintain` | Run maintenance operations (decay, consolidation, cleanup) | +| `omega_stats` | Memory store statistics and health metrics | +| `omega_lessons` | Cross-session lessons ranked by access frequency | + +## How to Add OMEGA Memory to Any Agent + +Add a **Memory Integration** section to an agent's prompt. See [memory-section-template.md](memory-section-template.md) for a ready-to-use template. + +The key differences from generic MCP memory instructions: + +1. **Use typed storage**: Instead of generic `remember`, use `omega_store` with `event_type` to categorize what you're storing (decision, lesson_learned, error_pattern, user_preference). +2. **Use semantic search**: `omega_query` with mode `semantic` finds relevant memories even when the exact wording differs from what was stored. +3. **Use checkpoints**: `omega_checkpoint` and `omega_resume_task` handle mid-session saves and cross-session continuity without manual bookkeeping. +4. **Session start protocol**: Call `omega_welcome()` at session start to get a context briefing, then `omega_protocol()` for operating instructions. + +## How It Enhances Agency Agents + +When agents in The Agency use OMEGA: + +- **Session continuity**: An agent resumes work without re-explaining context. The Backend Architect remembers the database schema it designed last week. +- **Cross-agent handoffs**: When the Backend Architect hands off to the Frontend Developer, the API spec is already in memory, tagged and searchable. +- **Learning from mistakes**: Error patterns and lessons learned persist. An agent that hit a race condition once will remember the fix next time. +- **Decision tracking**: Architecture decisions, their reasoning, and their outcomes are stored and searchable. No more re-litigating settled questions. + +## Example: Memory-Enhanced Workflow + +``` +Session 1 (Backend Architect): + -> omega_welcome() — gets context from prior sessions + -> Designs API schema + -> omega_store("API uses REST with JWT auth, rate limited at 100 req/min", + event_type="decision", metadata={"project": "acme"}) + -> omega_checkpoint("api-design-phase-1") + +Session 2 (Frontend Developer): + -> omega_welcome() — sees the Backend Architect's API decisions + -> omega_query("API authentication approach", mode="semantic") + -> Builds the frontend against the documented API contract +``` + +## Supported MCP Clients + +OMEGA works with any client that supports the Model Context Protocol: + +- **Claude Code** (Anthropic CLI) +- **Cursor** +- **Windsurf** +- **Zed** +- **Any MCP-compatible editor or agent framework** + +## Links + +- **GitHub**: [omega-memory/omega-memory](https://github.com/omega-memory/omega-memory) +- **PyPI**: [omega-memory](https://pypi.org/project/omega-memory/) +- **Skills**: [omega-memory/omega-skills](https://github.com/omega-memory/omega-skills) — battle-tested Claude Code skills enhanced by OMEGA memory +- **Documentation**: See the GitHub README for full setup and usage guide diff --git a/integrations/omega-memory/memory-section-template.md b/integrations/omega-memory/memory-section-template.md new file mode 100644 index 00000000..b01b2d82 --- /dev/null +++ b/integrations/omega-memory/memory-section-template.md @@ -0,0 +1,63 @@ +# Memory Integration Template (OMEGA) + +Add this section to the end of any agent's prompt file to enable persistent memory via OMEGA. + +--- + +## Memory Integration + +When you start a session, call `omega_welcome()` to load context from previous sessions. Review the briefing for prior decisions, pending tasks, and relevant context before proceeding. + +When you make a key decision — choosing a technology, defining a contract, setting a constraint — store it: + +``` +omega_store("Chose PostgreSQL for user data due to ACID requirements and JSON support", + event_type="decision", + metadata={"project": "project-name", "topic": "database"}) +``` + +When you learn something from a mistake or unexpected behavior, store it as a lesson: + +``` +omega_store("SQLite WAL mode required for concurrent read/write in multi-agent setups", + event_type="lesson_learned", + metadata={"project": "project-name"}) +``` + +When you encounter an error pattern worth remembering: + +``` +omega_store("Race condition in connection pool when >10 concurrent queries; fixed with semaphore", + event_type="error_pattern", + metadata={"project": "project-name"}) +``` + +When you need to find relevant context from past sessions, search semantically: + +``` +omega_query("database connection pooling strategy", mode="semantic") +``` + +When you need to pause and resume later, checkpoint your progress: + +``` +omega_checkpoint("Completed API routes for /users and /products. Next: /orders endpoint and auth middleware.") +``` + +When handing off to another agent, store a summary tagged for them: + +``` +omega_store("API spec complete: REST with JWT auth, 12 endpoints documented. Frontend can begin integration.", + event_type="task_completion", + metadata={"project": "project-name", "handoff_to": "frontend-developer"}) +``` + +When resuming a previous task: + +``` +omega_resume_task() +``` + +--- + +Copy the **Memory Integration** section above (everything between the `---` markers) and paste it at the end of any agent file. Replace `project-name` with the actual project name. diff --git a/integrations/omega-memory/setup.sh b/integrations/omega-memory/setup.sh new file mode 100755 index 00000000..217a8102 --- /dev/null +++ b/integrations/omega-memory/setup.sh @@ -0,0 +1,104 @@ +#!/usr/bin/env bash +# +# setup.sh -- Install OMEGA Memory, an MCP memory server for persistent agent memory. +# +# Usage: +# ./integrations/omega-memory/setup.sh + +set -euo pipefail + +echo "OMEGA Memory Integration Setup" +echo "===============================" +echo "" + +# Check for Python 3.11+ +PYTHON_CMD="" + +for cmd in python3.11 python3.12 python3.13 python3; do + if command -v "$cmd" &>/dev/null; then + version=$("$cmd" -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")') + major=$(echo "$version" | cut -d. -f1) + minor=$(echo "$version" | cut -d. -f2) + if [ "$major" -ge 3 ] && [ "$minor" -ge 11 ]; then + PYTHON_CMD="$cmd" + break + fi + fi +done + +if [ -z "$PYTHON_CMD" ]; then + echo "Error: Python 3.11+ is required but not found." + echo "" + echo "Install Python 3.11+ from https://www.python.org/downloads/" + echo "or via your package manager:" + echo " brew install python@3.11 # macOS" + echo " sudo apt install python3.11 # Ubuntu/Debian" + exit 1 +fi + +echo "Found $PYTHON_CMD ($($PYTHON_CMD --version))" +echo "" + +# Install omega-memory +echo "Installing omega-memory..." +$PYTHON_CMD -m pip install omega-memory +echo "" +echo "omega-memory installed." +echo "" + +# Check for existing MCP client configs +CONFIG_FOUND=false +CLAUDE_CONFIG="$HOME/.claude.json" + +if [ -f "$CLAUDE_CONFIG" ]; then + echo "Found Claude Code config at $CLAUDE_CONFIG" + CONFIG_FOUND=true + + # Check if omega is already configured + if grep -q '"omega"' "$CLAUDE_CONFIG" 2>/dev/null; then + echo "OMEGA is already configured in Claude Code." + else + echo "" + echo "Add OMEGA to your Claude Code config by adding this to the" + echo "\"mcpServers\" section in $CLAUDE_CONFIG:" + echo "" + echo ' "omega": {' + echo " \"command\": \"$PYTHON_CMD\"," + echo ' "args": ["-m", "omega.server.mcp_server"]' + echo ' }' + fi +fi + +if [ -f "$HOME/.cursor/mcp.json" ]; then + echo "Found Cursor config at ~/.cursor/mcp.json" + CONFIG_FOUND=true +fi + +if [ -f ".mcp.json" ]; then + echo "Found MCP config at .mcp.json" + CONFIG_FOUND=true +fi + +if [ "$CONFIG_FOUND" = false ]; then + echo "No MCP client config found." + echo "" + echo "Add OMEGA to your MCP client config:" + echo "" + echo ' {' + echo ' "mcpServers": {' + echo ' "omega": {' + echo " \"command\": \"$PYTHON_CMD\"," + echo ' "args": ["-m", "omega.server.mcp_server"]' + echo ' }' + echo ' }' + echo ' }' +fi + +echo "" +echo "Setup complete." +echo "" +echo "Next steps:" +echo " 1. Add OMEGA to your MCP client config (see above)" +echo " 2. Start a new session — OMEGA tools will be available automatically" +echo " 3. Add a Memory Integration section to any agent prompt" +echo " (see integrations/omega-memory/memory-section-template.md)"