{"id":42650026,"url":"https://github.com/muvon/octobrain","last_synced_at":"2026-04-19T20:01:49.553Z","repository":{"id":334403300,"uuid":"1141223919","full_name":"Muvon/octobrain","owner":"Muvon","description":"The brain for your LLM","archived":false,"fork":false,"pushed_at":"2026-04-08T11:53:34.000Z","size":1010,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-08T13:27:56.376Z","etag":null,"topics":["ai-agents","ai-memory","knowledge-graph","mcp-server","persistent-memory","rust"],"latest_commit_sha":null,"homepage":"https://octomind.run/product/octobrain/","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/Muvon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2026-01-24T13:34:45.000Z","updated_at":"2026-04-08T11:53:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"234ca5b2-a184-4ce8-ba95-6c2c8e0abb90","html_url":"https://github.com/Muvon/octobrain","commit_stats":null,"previous_names":["muvon/octobrain"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Muvon/octobrain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Muvon%2Foctobrain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Muvon%2Foctobrain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Muvon%2Foctobrain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Muvon%2Foctobrain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Muvon","download_url":"https://codeload.github.com/Muvon/octobrain/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Muvon%2Foctobrain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31575755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"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":["ai-agents","ai-memory","knowledge-graph","mcp-server","persistent-memory","rust"],"created_at":"2026-01-29T07:22:38.720Z","updated_at":"2026-04-08T22:02:02.172Z","avatar_url":"https://github.com/Muvon.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Octobrain\n\n\u003e Persistent memory for AI assistants — store insights, decisions, and knowledge that survives across conversations.\n\n[![Crates.io](https://img.shields.io/crates/v/octobrain.svg)](https://crates.io/crates/octobrain)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![Rust](https://img.shields.io/badge/rust-1.88%2B-orange.svg)](https://www.rust-lang.org/)\n\n**Octobrain** gives your AI assistant a long-term memory. Store code insights, architecture decisions, bug fixes, and knowledge — then retrieve them with semantic search in future sessions. Works as a CLI tool or as an MCP server for integration with Claude Desktop and other AI tools.\n\n## Why Octobrain?\n\nAI assistants start every conversation with zero context. You explain your project, your preferences, your decisions — every single time. Octobrain breaks that cycle:\n\n- **Persistent memory** — Insights survive across sessions, not just within them\n- **Semantic search** — Find memories by meaning, not exact keywords\n- **Auto-linking** — Related memories connect automatically (Zettelkasten-style)\n- **Knowledge indexing** — Ingest docs, articles, and files for retrieval\n- **MCP integration** — Works with Claude Desktop and other MCP-compatible tools\n\n## Quick Start\n\n```bash\n# Install from crates.io\ncargo install octobrain\n\n# Store your first memory\noctobrain memory memorize --title \"API Design Pattern\" \\\n  --content \"Use REST for CRUD, GraphQL for complex queries\" \\\n  --memory-type architecture --tags \"api,design\"\n\n# Search memories\noctobrain memory remember \"how should I design APIs\"\n\n# Start MCP server for Claude Desktop integration\noctobrain mcp\n```\n\n## Installation\n\n### From crates.io (Recommended)\n\n```bash\ncargo install octobrain\n```\n\n### From Source\n\n```bash\n# Clone and build\ngit clone https://github.com/muvon/octobrain.git\ncd octobrain\ncargo build --release\n\n# Binary location\n./target/release/octobrain --help\n```\n\n### Feature Flags\n\nOctobrain supports multiple embedding providers:\n\n| Flag | Description | API Key Required |\n|------|-------------|------------------|\n| `fastembed` | Local embeddings via FastEmbed | No |\n| `huggingface` | Local embeddings via HuggingFace | No |\n| (default) | Both `fastembed` + `huggingface` | No |\n| (no features) | API-based: Voyage, OpenAI, Google, Jina | Yes |\n\n```bash\n# Build with local embeddings (default, no API keys needed)\ncargo build --release\n\n# Build with API-based embeddings only\ncargo build --no-default-features --release\n```\n\nFor API-based embeddings, set the appropriate environment variable:\n- `VOYAGE_API_KEY` for Voyage AI\n- `OPENAI_API_KEY` for OpenAI\n- `GOOGLE_API_KEY` for Google\n- `JINA_API_KEY` for Jina\n\n## Usage\n\n### Memory Management\n\nStore and retrieve insights, decisions, and context:\n\n```bash\n# Store a memory\noctobrain memory memorize --title \"API Design\" \\\n  --content \"Use REST for CRUD, GraphQL for complex queries\" \\\n  --memory-type architecture --tags \"api,design\"\n\n# Search memories (semantic search)\noctobrain memory remember \"api design patterns\"\n\n# Multi-query search for broader coverage\noctobrain memory remember \"authentication\" \"security\" \"jwt\"\n\n# Get recent memories\noctobrain memory recent --limit 20\n\n# Filter by type\noctobrain memory by-type architecture --limit 10\n\n# Filter by tags\noctobrain memory by-tags \"api,security\"\n\n# Find memories related to files\noctobrain memory for-files \"src/main.rs,src/lib.rs\"\n\n# Update a memory\noctobrain memory update \u003cid\u003e --title \"New Title\" --add-tags \"new-tag\"\n\n# Delete a memory\noctobrain memory forget --memory-id \u003cid\u003e\n```\n\n### Memory Relationships\n\nConnect related memories for context-rich retrieval:\n\n```bash\n# Create a relationship between memories\noctobrain memory relate \u003csource-id\u003e \u003ctarget-id\u003e \\\n  --relationship-type \"depends_on\" \\\n  --description \"Source requires target to function\"\n\n# View relationships for a memory\noctobrain memory relationships \u003cmemory-id\u003e\n\n# Find related memories through relationships\noctobrain memory related \u003cmemory-id\u003e\n\n# Auto-link similar memories (Zettelkasten-style)\noctobrain memory auto-link \u003cmemory-id\u003e\n\n# Explore memory graph\noctobrain memory graph \u003cmemory-id\u003e --depth 2\n```\n\n### Knowledge Base\n\nIndex and search web content, docs, and files:\n\n```bash\n# Index a URL\noctobrain knowledge index https://docs.rs/tokio/latest/tokio/\n\n# Search knowledge base\noctobrain knowledge search \"how to handle async tasks\"\n\n# Search within a specific source (auto-indexes if outdated)\noctobrain knowledge search \"spawn blocking\" --source https://docs.rs/tokio/\n\n# Store raw text content\noctobrain knowledge store \"meeting-notes\" --content \"Discussion points...\"\n\n# List indexed sources\noctobrain knowledge list --limit 20\n\n# Show statistics\noctobrain knowledge stats\n\n# Delete a source\noctobrain knowledge delete https://example.com/docs\n```\n\n### MCP Server\n\nRun as an MCP server for integration with Claude Desktop and other AI tools:\n\n```bash\n# Start with stdio transport (for Claude Desktop)\noctobrain mcp\n\n# Start with HTTP transport (for web-based tools)\noctobrain mcp --bind 0.0.0.0:12345\n```\n\n**Available MCP Tools:**\n\n| Tool | Description |\n|------|-------------|\n| `memorize` | Store memories with metadata |\n| `remember` | Semantic search with filters |\n| `forget` | Delete memories (requires confirmation) |\n| `relate` | Create relationships between memories |\n| `auto_link` | Auto-connect similar memories |\n| `memory_graph` | Explore memory relationships |\n| `knowledge_search` | Search indexed knowledge |\n\nSee [MCP Integration](#mcp-integration) for Claude Desktop setup.\n\n## Features\n\n- **Semantic Search** — Find memories by meaning using vector embeddings, not exact keyword matches\n- **Hybrid Search** — Combines BM25 full-text search with vector similarity for better results\n- **Reranking Support** — Optional cross-encoder reranking for 20-35% accuracy improvement\n- **Auto-Linking** — Automatically connects semantically similar memories (Zettelkasten-style)\n- **Temporal Decay** — Ebbinghaus forgetting curve for importance management\n- **Knowledge Indexing** — Ingest URLs, PDFs, docs for retrieval\n- **Project Scoping** — Isolate memories per Git project or share across projects\n- **Role Filtering** — Tag memories by role (developer, reviewer, etc.)\n- **MCP Protocol** — Full MCP 2025-11-25 compliance for AI tool integration\n\n## Configuration\n\nConfiguration is stored in `~/.local/share/octobrain/config.toml`. All options have sensible defaults.\n\n### Key Settings\n\n| Section | Option | Default | Description |\n|---------|--------|---------|-------------|\n| `[embedding]` | `model` | `voyage:voyage-3.5-lite` | Embedding model (provider:model format) |\n| `[search]` | `similarity_threshold` | `0.3` | Minimum relevance (0.0-1.0) |\n| `[search.hybrid]` | `enabled` | `true` | Enable BM25 + vector fusion |\n| `[search.reranker]` | `enabled` | `false` | Enable cross-encoder reranking |\n| `[memory]` | `max_memories` | `10000` | Maximum stored memories |\n| `[memory]` | `decay_enabled` | `true` | Enable temporal importance decay |\n| `[memory]` | `auto_linking_enabled` | `true` | Auto-connect similar memories |\n| `[knowledge]` | `chunk_size` | `1200` | Characters per chunk |\n\n### Embedding Providers\n\n```toml\n[embedding]\n# Local embeddings (no API key needed)\nmodel = \"voyage:voyage-3.5-lite\"  # Fast, accurate\nmodel = \"openai:text-embedding-3-small\"  # OpenAI\nmodel = \"google:text-embedding-004\"  # Google\nmodel = \"jina:jina-embeddings-v2\"  # Jina\n```\n\n### Full Configuration\n\nSee [`config-templates/default.toml`](config-templates/default.toml) for all available options with documentation.\n\n## Memory Types\n\nOrganize memories by category for better filtering:\n\n| Type | Use For |\n|------|---------|\n| `code` | Code patterns, solutions, implementations |\n| `architecture` | System design, decisions, patterns |\n| `bug_fix` | Bug fixes, troubleshooting, solutions |\n| `feature` | Feature specs, implementations |\n| `documentation` | Docs, explanations, knowledge |\n| `user_preference` | Settings, preferences, workflows |\n| `decision` | Project decisions, trade-offs |\n| `learning` | Tutorials, notes, education |\n| `configuration` | Setup, config, deployment |\n| `testing` | Test strategies, QA insights |\n| `performance` | Optimizations, benchmarks |\n| `security` | Vulnerabilities, fixes, considerations |\n| `insight` | General insights, tips |\n\n## MCP Integration\n\n### Claude Desktop Setup\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"octobrain\": {\n      \"command\": \"/path/to/octobrain\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Octobrain tools will be available in your conversations.\n\n### HTTP Transport\n\nFor web-based integrations:\n\n```bash\noctobrain mcp --bind 0.0.0.0:12345\n```\n\nThe server exposes endpoints at `/mcp` for MCP protocol communication.\n\n## Storage Locations\n\nData is stored in platform-specific directories:\n\n| Platform | Location |\n|----------|----------|\n| macOS | `~/.local/share/octobrain/` |\n| Linux | `~/.local/share/octobrain/` or `$XDG_DATA_HOME/octobrain/` |\n| Windows | `%APPDATA%\\octobrain\\` |\n\nProject-specific memories are isolated by Git remote URL hash.\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. Run `cargo clippy` and fix all warnings\n4. Run `cargo test --no-default-features`\n5. Submit a pull request\n\n### Development Setup\n\n```bash\n# Clone and build\ngit clone https://github.com/muvon/octobrain.git\ncd octobrain\ncargo build --no-default-features\n\n# Run tests\ncargo test --no-default-features\n\n# Run clippy\ncargo clippy --no-default-features\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n\n## Credits\n\nDeveloped by [Muvon Un Limited](https://muvon.io).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuvon%2Foctobrain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuvon%2Foctobrain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuvon%2Foctobrain/lists"}