{"id":42601144,"url":"https://github.com/conarylabs/mira","last_synced_at":"2026-03-01T06:06:29.870Z","repository":{"id":318757199,"uuid":"1022316217","full_name":"ConaryLabs/Mira","owner":"ConaryLabs","description":"Persistent intelligence layer for Claude Code. Long-term memory, semantic code search, change intelligence, team coordination, and background analysis — all local, all automatic.","archived":false,"fork":false,"pushed_at":"2026-02-25T04:41:01.000Z","size":57333,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-25T04:52:21.764Z","etag":null,"topics":["agent-teams","ai-memory","anthropic","claude","claude-code","claude-code-plugin","code-intelligence","developer-tools","mcp","mcp-server","rust","semantic-search","sqlite","tree-sitter"],"latest_commit_sha":null,"homepage":"https://github.com/ConaryLabs/Mira","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ConaryLabs.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":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-07-18T20:42:40.000Z","updated_at":"2026-02-25T04:41:05.000Z","dependencies_parsed_at":"2026-02-18T08:02:42.682Z","dependency_job_id":null,"html_url":"https://github.com/ConaryLabs/Mira","commit_stats":null,"previous_names":["conarylabs/mira"],"tags_count":49,"template":false,"template_full_name":null,"purl":"pkg:github/ConaryLabs/Mira","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ConaryLabs%2FMira","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ConaryLabs%2FMira/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ConaryLabs%2FMira/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ConaryLabs%2FMira/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ConaryLabs","download_url":"https://codeload.github.com/ConaryLabs/Mira/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ConaryLabs%2FMira/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29962001,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T05:59:08.471Z","status":"ssl_error","status_checked_at":"2026-03-01T05:58:04.208Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["agent-teams","ai-memory","anthropic","claude","claude-code","claude-code-plugin","code-intelligence","developer-tools","mcp","mcp-server","rust","semantic-search","sqlite","tree-sitter"],"created_at":"2026-01-29T01:01:16.298Z","updated_at":"2026-03-01T06:06:29.862Z","avatar_url":"https://github.com/ConaryLabs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mira\n\n[![CI](https://github.com/ConaryLabs/Mira/actions/workflows/ci.yml/badge.svg)](https://github.com/ConaryLabs/Mira/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/ConaryLabs/Mira)](https://github.com/ConaryLabs/Mira/releases/latest)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n\n**The intelligence layer that makes Claude Code dangerous.**\n\nClaude Code is powerful but amnesiac. Every session starts from scratch — architecture decisions gone, codebase reduced to what it can grep. You spend the first ten minutes re-explaining things it knew yesterday.\n\nMira eliminates that. It's a local Rust MCP server that gives Claude Code persistent memory, deep code understanding, background analysis, and continuous learning. Runs on your machine, stored in SQLite, 13 hooks that make it all automatic.\n\n## The Short Version\n\n```bash\nclaude plugin install mira\nmira setup  # optional: configure API keys for enhanced features\n```\n\nThat's it. Mira auto-configures itself, starts injecting context on every prompt, and indexes your codebase in the background.\n\n## What Changes\n\n### Before Mira\n- Every session starts cold. Claude doesn't know your preferences, your patterns, your past decisions.\n- Code search is grep. \"Find the authentication logic\" returns nothing if nobody wrote the word \"authentication.\"\n- Agent teams work in isolation. No shared context, no conflict detection.\n- You are the memory. Every conversation requires re-establishing context.\n\n### With Mira\n- **Sessions have continuity.** Decisions, preferences, and context persist and surface automatically on every prompt.\n- **Search works by meaning.** \"Where do we handle auth?\" finds `verify_credentials` in `middleware.rs`. Hybrid semantic + keyword search with call graph traversal.\n- **The codebase is always understood.** Background workers track code health, score tech debt, detect doc gaps, and surface insights — without you asking.\n- **Changes are analyzed, not just diffed.** Semantic classification, call graph impact tracing, risk scoring based on historical churn patterns.\n- **Agent teams share a brain.** File ownership tracking, conflict detection, and built-in recipes for expert review, QA hardening, and safe refactoring.\n- **Knowledge compounds.** Memories gain confidence through repeated use and get distilled into higher-level insights over time.\n- **Cross-project knowledge.** Mira surfaces relevant solutions from your other projects when applicable.\n- **Token-efficient by design.** Hooks inject only what matters: tight semantic thresholds, cross-prompt dedup, type-aware subagent budgets, file-read caching, and symbol hints for large files. Context that isn't used gets tracked and suppressed. Run `/mira:efficiency` to see injection hit rates.\n\n## How It Works\n\n```\nClaude Code  \u003c--MCP (stdio)--\u003e  Mira  \u003c--\u003e  SQLite + sqlite-vec\n    |                             |\n    +--13 lifecycle hooks         +---\u003e  OpenAI (embeddings, optional)\n    +--MCP Sampling (host LLM)   +---\u003e  DeepSeek / Ollama (background tasks, optional)\n```\n\nEverything runs locally. Two SQLite databases in `~/.mira/`: one for memories, sessions, and goals; one for the code index. No cloud, no accounts, no external databases.\n\n**No API keys required.** Memory, code intelligence, goal tracking, and documentation detection all work out of the box — search falls back to keyword/fuzzy matching, analysis uses heuristic parsers. OpenAI for semantic search and DeepSeek/Ollama for background intelligence are there when you want them.\n\n## Installation\n\n### Quick Install (Recommended)\n\n```bash\nclaude plugin install mira\n```\n\nThen optionally configure providers:\n```bash\nmira setup          # interactive wizard with live validation + Ollama auto-detection\nmira setup --yes    # non-interactive (CI/scripted installs)\nmira setup --check  # read-only validation\n```\n\nTo verify: start a new Claude Code session in any project. You should see \"Mira: Loading session context...\" in the status bar.\n\n### Alternative: Script Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/ConaryLabs/Mira/main/install.sh | bash\n```\n\nDetects your OS, downloads the binary, installs the Claude Code plugin (auto-configures all hooks and skills), and creates `~/.mira/`.\n\n### Manual Install\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand manual installation options\u003c/summary\u003e\n\n#### Download Binary\n\n**Linux/macOS:**\n```bash\n# Linux (x86_64)\ncurl -L https://github.com/ConaryLabs/Mira/releases/latest/download/mira-x86_64-unknown-linux-gnu.tar.gz | tar xz\nsudo mv mira /usr/local/bin/\n\n# macOS (Apple Silicon)\ncurl -L https://github.com/ConaryLabs/Mira/releases/latest/download/mira-aarch64-apple-darwin.tar.gz | tar xz\nsudo mv mira /usr/local/bin/\n\n# macOS (Intel)\ncurl -L https://github.com/ConaryLabs/Mira/releases/latest/download/mira-x86_64-apple-darwin.tar.gz | tar xz\nsudo mv mira /usr/local/bin/\n```\n\n**Windows (PowerShell):**\n```powershell\nInvoke-WebRequest -Uri \"https://github.com/ConaryLabs/Mira/releases/latest/download/mira-x86_64-pc-windows-msvc.zip\" -OutFile mira.zip\nExpand-Archive mira.zip -DestinationPath .\nRemove-Item mira.zip\nMove-Item mira.exe C:\\Tools\\  # Or another directory in your PATH\n```\n\n#### Install Plugin\n\n```bash\nclaude plugin install ConaryLabs/Mira\n```\n\n\u003c/details\u003e\n\n### Install via Cargo (MCP Server Only)\n\n```bash\ncargo install --git https://github.com/ConaryLabs/Mira.git\n```\n\nThen add to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mira\": {\n      \"command\": \"mira\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\nIf you use Codex CLI, add Mira to `.codex/config.toml`:\n\n```toml\n#:schema https://developers.openai.com/codex/config-schema.json\nproject_doc_fallback_filenames = [\"CLAUDE.md\"]\n\n[mcp_servers.mira]\ncommand = \"mira\"\nargs = [\"serve\"]\nrequired = true\nstartup_timeout_sec = 20\ntool_timeout_sec = 90\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/ConaryLabs/Mira.git\ncd Mira\ncargo build --release\n```\n\nBinary lands at `target/release/mira`. Add to `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mira\": {\n      \"command\": \"/path/to/mira\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### Enable Hooks (Manual Installs Only)\n\nPlugin install handles this automatically. For MCP-only installs, add to `~/.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [{\"hooks\": [{\"type\": \"command\", \"command\": \"mira hook session-start\", \"timeout\": 10}]}],\n    \"UserPromptSubmit\": [{\"hooks\": [{\"type\": \"command\", \"command\": \"mira hook user-prompt\", \"timeout\": 8}]}],\n    \"PermissionRequest\": [{\"hooks\": [{\"type\": \"command\", \"command\": \"mira hook permission\", \"timeout\": 3}]}],\n    \"PreToolUse\": [{\"matcher\": \"Grep|Glob|Read\", \"hooks\": [{\"type\": \"command\", \"command\": \"mira hook pre-tool\", \"timeout\": 3}]}],\n    \"PostToolUse\": [{\"matcher\": \"Write|Edit|NotebookEdit|Bash\", \"hooks\": [{\"type\": \"command\", \"command\": \"mira hook post-tool\", \"timeout\": 5}]}],\n    \"PreCompact\": [{\"matcher\": \"*\", \"hooks\": [{\"type\": \"command\", \"command\": \"mira hook pre-compact\", \"timeout\": 30, \"async\": true}]}],\n    \"Stop\": [{\"hooks\": [{\"type\": \"command\", \"command\": \"mira hook stop\", \"timeout\": 8}]}],\n    \"SessionEnd\": [{\"hooks\": [{\"type\": \"command\", \"command\": \"mira hook session-end\", \"timeout\": 15}]}],\n    \"SubagentStart\": [{\"hooks\": [{\"type\": \"command\", \"command\": \"mira hook subagent-start\", \"timeout\": 3}]}],\n    \"SubagentStop\": [{\"hooks\": [{\"type\": \"command\", \"command\": \"mira hook subagent-stop\", \"timeout\": 3, \"async\": true}]}],\n    \"PostToolUseFailure\": [{\"hooks\": [{\"type\": \"command\", \"command\": \"mira hook post-tool-failure\", \"timeout\": 5, \"async\": true}]}],\n    \"TaskCompleted\": [{\"hooks\": [{\"type\": \"command\", \"command\": \"mira hook task-completed\", \"timeout\": 5}]}],\n    \"TeammateIdle\": [{\"hooks\": [{\"type\": \"command\", \"command\": \"mira hook teammate-idle\", \"timeout\": 5}]}]\n  }\n}\n```\n\n### Plugin vs MCP Server\n\nThe **plugin** (quick install) is the full experience — hooks and skills auto-configured, context injected on every prompt.\n\nThe **MCP server** (cargo install / build from source) gives you the core tools. Add hooks manually for the proactive stuff.\n\n### Add Mira Instructions to Your Project\n\nSee **[docs/CLAUDE_TEMPLATE.md](docs/CLAUDE_TEMPLATE.md)** for a recommended `CLAUDE.md` layout that teaches Claude Code how to use Mira's tools. The structure:\n\n- `CLAUDE.md` — Core identity, anti-patterns, build commands (always loaded)\n- `.claude/rules/` — Tool selection, memory, tasks (always loaded)\n\n## Slash Commands\n\n| Command | What it does |\n|---------|-------------|\n| `/mira:recap` | Session context, preferences, and active goals |\n| `/mira:goals` | List and manage cross-session goals |\n| `/mira:search \u003cquery\u003e` | Semantic code search |\n| `/mira:remember \u003ctext\u003e` | Quick memory storage |\n| `/mira:recall [query]` | Browse or search stored memories |\n| `/mira:diff` | Semantic analysis of recent changes |\n| `/mira:insights` | Surface background analysis |\n| `/mira:experts` | Expert consultation via Agent Teams |\n| `/mira:full-cycle` | End-to-end review, implementation, and QA |\n| `/mira:qa-hardening` | Production readiness review |\n| `/mira:refactor` | Safe code restructuring with validation |\n| `/mira:help` | Show all available Mira commands and tools |\n| `/mira:status` | Quick health check: index, storage, goals |\n\n## Capabilities at a Glance\n\n| Capability | Without API Keys | With API Keys |\n|-----------|-----------------|---------------|\n| Memory \u0026 recall | Keyword/fuzzy search | Semantic search (OpenAI embeddings) |\n| Code search | FTS5 + fuzzy matching | Hybrid semantic + keyword |\n| Code intelligence | Tree-sitter symbols, call graph | Same |\n| Diff analysis | Heuristic pattern detection | LLM-powered semantic classification |\n| Module summaries | File counts, symbol names | LLM-generated descriptions |\n| Background insights | Tool usage analysis, friction detection | LLM-powered pattern extraction |\n| Goal tracking | Full | Full |\n| Agent team coordination | Full | Full |\n| Error pattern learning | Remembers how errors were fixed across sessions — Claude gets the solution faster next time | Same |\n| Memory poisoning defense | Prompt injection attempts in memory writes are detected and flagged | Same |\n\nOpenAI embeddings use text-embedding-3-small, which typically costs less than $1/month for normal development usage.\n\n## Troubleshooting\n\n### Semantic search not working\n\nMake sure `OPENAI_API_KEY` is set in `~/.mira/.env`. Without it, search falls back to keyword and fuzzy matching.\n\n### MCP connection issues\n\n1. Check the binary path in `.mcp.json` is absolute\n2. Run `mira serve` directly and confirm it starts without errors\n3. Check Claude Code logs for MCP errors\n\n### Memory not persisting\n\nProject context is auto-initialized from Claude Code's working directory. Run `project(action=\"get\")` to verify Mira is running and that the working directory matches your project root.\n\n### CLI Commands\n\n```bash\nmira setup                # Interactive configuration wizard\nmira setup --check        # Validate current configuration\nmira index                # Index current project for semantic code search\nmira index --no-embed     # Index without embeddings (faster, keyword-only search)\nmira debug-session        # Debug project(action=\"start\") output\nmira debug-carto          # Debug cartographer module detection\nmira config show          # Display current configuration\nmira config set \u003ck\u003e \u003cv\u003e   # Update a configuration value\nmira statusline           # Formatted status line for Claude Code's status bar (installed automatically)\nmira cleanup              # Data retention dry-run (sessions, analytics, behavior)\nmira cleanup --execute    # Actually delete accumulated data (add --yes to skip confirmation)\n```\n\n## Documentation\n\n- [Design Philosophy](docs/DESIGN.md) — Architecture decisions and tradeoffs\n- [Core Concepts](docs/CONCEPTS.md) — Memory, intelligence, sessions explained\n- [Configuration](docs/CONFIGURATION.md) — All options and hooks\n- [Database](docs/DATABASE.md) — Schema and storage details\n- [Testing](docs/TESTING.md) — Test infrastructure and patterns\n- [Tool Reference](docs/tools/) — Per-tool documentation (memory, code, goal, etc.)\n- [Module Reference](docs/modules/) — Internal module documentation\n- [Changelog](CHANGELOG.md) — Version history\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## Support\n\n- [Report Issues](https://github.com/ConaryLabs/Mira/issues)\n- [Discussions](https://github.com/ConaryLabs/Mira/discussions)\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconarylabs%2Fmira","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconarylabs%2Fmira","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconarylabs%2Fmira/lists"}