{
  "markdown": "# Octobrain\n\n> 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.95%2B-orange.svg)](https://www.rust-lang.org/)\n[![CI](https://github.com/Muvon/octobrain/actions/workflows/ci.yml/badge.svg)](https://github.com/Muvon/octobrain/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmuvon%2Foctobrain%2Fbadges%2Fcoverage.json&style=flat-square)](https://github.com/Muvon/octobrain/actions/workflows/ci.yml)\n\n_MCP Registry: `mcp-name: io.github.Muvon/octobrain`_\n\n## Table of Contents\n- [Why Octobrain?](#why-octobrain)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Features](#features)\n- [Benchmarks](#benchmarks)\n- [Configuration](#configuration)\n- [Memory Types](#memory-types)\n- [MCP Integration](#mcp-integration)\n- [Storage Locations](#storage-locations)\n- [Contributing](#contributing)\n- [License](#license)\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### Docker\n\n```bash\ndocker pull ghcr.io/muvon/octobrain:latest\n```\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew install muvon/tap/octobrain\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\n### Shell Completions\n\n```bash\nmake install-completions  # bash, zsh, fish\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\nAll `memory` subcommands accept global flags:\n- `--scope <string>` — Override project scope (default: auto-detected from Git remote)\n- `--role <string>` — Filter by role (e.g. \"developer\", \"reviewer\")\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 a memory by ID\noctobrain memory get <id>\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 <id> --title \"New Title\" --add-tags \"new-tag\"\n\n# Delete a memory\noctobrain memory forget --memory-id <id>\n\n# Get memories relevant to the current Git commit\noctobrain memory current-commit\n\n# Show memory statistics\noctobrain memory stats\n\n# Clean up old/low-importance memories\noctobrain memory cleanup\n\n# ⚠️ Delete ALL memory data\noctobrain memory clear-all --yes\n```\n\n### Memory Consolidation\n\nClose a goal and fold all its contributing memories into a consolidated summary:\n\n```bash\n# Consolidate a goal (all Achieves-link sources get archived)\noctobrain memory consolidate <goal-id> --summary \"Final summary\"\n\n# Sleep consolidation: auto-cluster recent similar memories\noctobrain memory sleep-consolidate --threshold 0.85 --min-size 3\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 <source-id> <target-id> \\\n  --relationship-type \"depends_on\" \\\n  --description \"Source requires target to function\"\n\n# View relationships for a memory\noctobrain memory relationships <memory-id>\n\n# Find related memories through relationships\noctobrain memory related <memory-id>\n\n# Auto-link similar memories (Zettelkasten-style)\noctobrain memory auto-link <memory-id>\n\n# Explore memory graph\noctobrain memory graph <memory-id> --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# Index a local file (.txt, .md, .pdf, .docx, .html)\noctobrain knowledge index ./docs/architecture.md\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# Read full content of a URL or local file\noctobrain knowledge read https://docs.rs/tokio/latest/tokio/\n\n# Search indexed content by regex pattern\noctobrain knowledge match \"spawn_blocking|block_in_place\"\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# Delete stored content by key\noctobrain knowledge delete-stored \"meeting-notes\"\n```\n\n### Knowledge Boxes\n\nImport and sync git-backed knowledge bundles scoped to your projects:\n\n```bash\n# Import a remote git repo as a knowledge box\noctobrain box import https://github.com/org/docs-repo.git\n\n# Import at global scope (visible in every project)\noctobrain box import https://github.com/org/docs-repo.git --global\n\n# Pull and re-index all subscribed boxes + local .box/ directories\noctobrain box sync\n\n# List subscribed boxes\noctobrain box list\n\n# Remove a box\noctobrain box remove github.com/org/docs-repo\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; optional `related_to` for inline relationships |\n| `remember` | Semantic search with filters; returns 1-hop graph neighbors |\n| `forget` | Delete memories (requires confirmation) |\n| `knowledge` | Unified tool: `search`, `store`, `delete`, `read`, `match` via `command` field |\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** — Pluggable cross-encoder reranking stage (provider-dependent)\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- **Query Expansion (HyDE-lite)** — Pseudo-relevance feedback for +10-30% recall on long-tail queries\n- **MCP Protocol** — Full MCP 2026-07-28 compliance for AI tool integration\n\n## Benchmarks\n\nRetrieval quality of octobrain's knowledge system on standard [BEIR](https://github.com/beir-cellar/beir) datasets — **nDCG@10**, fully local, no LLM judge, using the default local embedder `bge-small-en-v1.5` (384-dim, 33M params). Each corpus passage is indexed through octobrain's real retrieval path and scored against the official qrels (metrics reproduce `pytrec_eval`).\n\n| Dataset | octobrain vector | octobrain hybrid | BM25¹ | bge-small-en-v1.5² |\n|---|---|---|---|---|\n| **SciFact** (5.2K docs, 300 q) | 0.722 | **0.742** | 0.665 | 0.713 |\n| **NFCorpus** (3.6K docs, 323 q) | 0.341 | **0.363** | 0.325 | 0.343 |\n\n- **vector** = dense-only retrieval; reproduces the embedder's published BEIR numbers (validates the harness).\n- **hybrid** = BM25 + vector fused with Reciprocal Rank Fusion (k=60) — octobrain's default. Adds **+2 nDCG@10** over the bare embedding and beats classic BM25 on both datasets.\n\n¹ Canonical BM25 from the [BEIR paper](https://arxiv.org/abs/2104.08663) (Anserini/Lucene, k1=0.9 b=0.4).\n² From the [bge-small-en-v1.5 model card](https://huggingface.co/BAAI/bge-small-en-v1.5) (MTEB).\n\n> Scope: this measures the **ranking** layer (embedding + BM25 fusion + reranking). BEIR passages are pre-chunked, so octobrain's chunking strategy is not exercised here.\n\n> ⚠️ **Reranker status:** The cross-encoder reranker is currently a no-op with fastembed models (byte-identical results to hybrid-only). Rerank is excluded from the numbers above pending investigation. See [`benches/README.md`](benches/README.md#findings) for details.\n\nReproduce (downloads the datasets, builds a release binary, runs fully offline):\n\n```bash\ncd benches && bash scripts/run_retrieval.sh\n```\n\n## Configuration\n\nConfiguration is stored in `~/.local/share/octobrain/config.toml`. All options have sensible defaults.\n\nOverride the config location with `OCTOBRAIN_CONFIG_PATH=/path/to/config.toml`.\n\n### Key Settings\n\n| Section | Option | Default | Description |\n|---------|--------|---------|-------------|\n| `[embedding]` | `model` | `fastembed:nomic-ai/nomic-embed-text-v1.5` | Embedding model (provider:model format). Default is a local fastembed model — no API key, runs on CPU. |\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` | `true` | Enable cross-encoder reranking |\n| `[search.hyde]` | `enabled` | `true` | Pseudo-relevance feedback query expansion |\n| `[memory]` | `max_memories` | `10000` | Maximum stored memories |\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 models (no API key, runs on CPU, model auto-downloaded on first use)\nmodel = \"fastembed:nomic-ai/nomic-embed-text-v1.5\"                      # Default: 768-dim, 8192-token context\nmodel = \"fastembed:BAAI/bge-small-en-v1.5\"                              # 384-dim, ~62 MTEB, fast + good quality\nmodel = \"fastembed:sentence-transformers/all-MiniLM-L6-v2-quantized\"  # Smallest (~22MB), fastest\nmodel = \"fastembed:BAAI/bge-base-en-v1.5\"                              # Larger (~440MB), higher quality\nmodel = \"fastembed:intfloat/multilingual-e5-small\"                     # Multilingual\n\n# Cloud providers (require API keys, generally higher quality)\nmodel = \"voyage:voyage-3.5-lite\"          # VOYAGE_API_KEY\nmodel = \"openai:text-embedding-3-small\"   # OPENAI_API_KEY\nmodel = \"google:text-embedding-004\"       # GOOGLE_API_KEY\nmodel = \"jina:jina-embeddings-v3\"         # JINA_API_KEY\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| `validation` | Idea/product validation, hypothesis testing |\n| `research` | Technical/market research, analysis |\n| `workflow` | SOPs, playbooks, process descriptions |\n| `requirement` | Business requirements, specs, constraints |\n| `design` | UI/UX decisions, wireframes, system design |\n| `integration` | API integrations, third-party services |\n| `communication` | Stakeholder updates, team decisions |\n| `process` | Deployment procedures, runbooks, operations |\n| `insight` | General insights, tips |\n| `goal` | Task/intent anchors for consolidation workflow |\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 normalized Git remote URL (e.g., `github.com/org/repo`).\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 fmt --all` to format code\n4. Run `cargo clippy` and fix all warnings\n5. Run `cargo test --no-default-features`\n6. 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",
  "bytes": 15898,
  "sha": "3fc944c7ea7142b20178576188c25ce0474252339fcbe27cdb1886863aedf245",
  "repo_slug": "muvon/octobrain",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_muvon_octobrain_0ee419ad/readme"
}