{"id":46136092,"url":"https://github.com/mlorentedev/hive","last_synced_at":"2026-06-06T02:08:27.202Z","repository":{"id":341497200,"uuid":"1170337959","full_name":"mlorentedev/hive","owner":"mlorentedev","description":"Context infrastructure for AI-assisted development — on-demand Obsidian vault access via MCP","archived":false,"fork":false,"pushed_at":"2026-05-31T02:05:49.000Z","size":1180,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-31T03:18:47.991Z","etag":null,"topics":["ai","claude-code","context-management","developer-tools","mcp","obsidian","python","vault"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/hive-vault/","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/mlorentedev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-03-02T02:27:48.000Z","updated_at":"2026-05-31T02:05:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"a7da0cb1-2fbb-4b2e-a745-70a1579d66bb","html_url":"https://github.com/mlorentedev/hive","commit_stats":null,"previous_names":["mlorentedev/hive"],"tags_count":54,"template":false,"template_full_name":null,"purl":"pkg:github/mlorentedev/hive","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fhive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fhive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fhive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fhive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlorentedev","download_url":"https://codeload.github.com/mlorentedev/hive/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlorentedev%2Fhive/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33805341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"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","claude-code","context-management","developer-tools","mcp","obsidian","python","vault"],"created_at":"2026-03-02T05:11:44.467Z","updated_at":"2026-06-02T04:00:39.980Z","avatar_url":"https://github.com/mlorentedev.png","language":"Python","funding_links":[],"categories":["カテゴリ"],"sub_categories":["📁 \u003ca name=\"file-system--storage\"\u003e\u003c/a\u003eファイルシステム・ストレージ"],"readme":"# hive-vault\n\n[![CI](https://github.com/mlorentedev/hive/actions/workflows/ci.yml/badge.svg)](https://github.com/mlorentedev/hive/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/mlorentedev/hive/graph/badge.svg)](https://codecov.io/gh/mlorentedev/hive)\n[![PyPI](https://img.shields.io/pypi/v/hive-vault)](https://pypi.org/project/hive-vault/)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://python.org)\n[![Docs](https://img.shields.io/badge/docs-hive-blue)](https://mlorentedev.github.io/hive/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003ca href=\"https://glama.ai/mcp/servers/mlorentedev/hive\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/mlorentedev/hive/badge\" /\u003e\n\u003c/a\u003e\n\n\u003c!-- mcp-name: io.github.mlorentedev/hive-vault --\u003e\n\n**Your AI coding assistant forgets everything between sessions. Hive fixes that.**\n\nHive is an [MCP](https://modelcontextprotocol.io/) server that connects your AI assistant to an [Obsidian](https://obsidian.md/) vault. Instead of loading everything upfront, it queries only what's needed — on demand.\n\n| Metric | Without Hive | With Hive |\n|---|---|---|\n| Context loaded per session | ~800 lines (static) | ~50 lines (on demand) |\n| Token cost for context | 100% every session | 6% average per query |\n| Knowledge retained between sessions | 0% | 100% (in vault) |\n\n\u003e Measured on a real vault with 19 projects, 200+ files. See [benchmarks](https://mlorentedev.github.io/hive/guides/benchmarks/).\n\n## Quick Start\n\nHive runs without a vault — vault tools return a friendly error until `VAULT_PATH` is set, so you can install first and configure later.\n\n```bash\n# Minimal — uses default vault path ~/Projects/knowledge\nclaude mcp add -s user hive -- uvx --upgrade hive-vault\n\n# With a custom vault path\nclaude mcp add -s user hive -e VAULT_PATH=$HOME/path/to/vault -- uvx --upgrade hive-vault\n\n# Gemini CLI\ngemini mcp add -s user -e VAULT_PATH=$HOME/path/to/vault hive-vault uvx -- --upgrade hive-vault\n```\n\n\u003e Default vault path: `~/Projects/knowledge`. Override with `VAULT_PATH` (or `HIVE_VAULT_PATH`) as shown above.\n\nFor Codex CLI, GitHub Copilot, Cursor, Windsurf, and other clients, see [Getting Started](https://mlorentedev.github.io/hive/getting-started/).\n\nThen ask your assistant: *\"Use vault_list to see my vault\"*\n\n## Requirements\n\nHive degrades gracefully — every recommended or optional dependency reveals more capability without breaking the baseline.\n\n- **Required**\n  - Python **3.12+** (works on 3.13).\n  - A directory of markdown files. The vault structure used by `00_meta` / `10_projects` / `50_work` / `80_agents` is optional — without it, vault tools still operate but the scope routing is flat.\n\n- **Recommended**\n  - `git` initialised inside the vault. Without it, `vault_write` / `vault_patch` still write to disk; they just skip the per-write commit (and `vault_commit` reports the working tree as untracked).\n  - The **[Obsidian](https://obsidian.md)** desktop app to author the vault by hand.\n  - The **[obsidian-git plugin](https://github.com/Vinzent03/obsidian-git)** with auto-commit set to **5–10 minutes**. Pair it with `vault_write(commit=False)` / `vault_patch(commit=False)` to push the git workload off the synchronous tool path; see *Recommended configuration* below.\n\n- **Optional**\n  - **[Ollama](https://ollama.com/)** running `qwen2.5-coder:7b` (or compatible) for local, free `delegate_task` / `capture_lesson` worker calls.\n  - An **OpenRouter** API key (`OPENROUTER_API_KEY`) as a free-tier and paid fallback worker.\n  - A **backup git remote** (e.g. private GitHub repo) so vault history survives a disk loss.\n\n### Recommended configuration\n\nPer [ADR-006 (commit policy)](docs/adr/adr-006-commit-policy.md), the recommended pairing for write-heavy flows is:\n\n1. Install and enable the **obsidian-git** plugin in your vault.\n2. Set its **auto-commit interval** to 5 or 10 minutes.\n3. Call `vault_write(..., commit=False)` and `vault_patch(..., commit=False)` for all bulk operations.\n4. Optionally call `vault_commit(message=\"...\")` at the end of a session to force a checkpoint sooner than the obsidian-git tick.\n\n`vault_health` reports a `## external_committer` block when it detects obsidian-git in the vault. The `commit=False` durability contract is explicit: files are persisted to disk regardless; only the *commit* is deferred. A crash before the next flush loses the commit, not the content.\n\nWhen a tool call is cancelled mid-flight (slow worker, client timeout), the server may have already mutated the disk before the cancel ack reaches the wire. `vault_health` surfaces a `## ghost_responses` counter and emits a `mcp.ghost_response.suppressed_after_cancel_ack` WARNING for each event — verify state via `vault_query` rather than retrying, since the ErrorData ack does **not** imply rollback ([ADR-007](docs/adr/adr-007-mcp-cancellation-response.md)).\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `vault_query` | Load project context, tasks, roadmap, lessons — or any file by path |\n| `vault_search` | Full-text search with metadata filters, regex, ranked results, recent changes, lesson-usage ranking (`rank_by`) |\n| `vault_list` | Browse projects and files with glob filtering |\n| `vault_health` | Server identity (version, vault path, backends), health metrics, drift detection, usage stats, opt-in runtime block |\n| `vault_write` | Create, append, or replace vault files. `commit=False` defers the git commit for batching |\n| `vault_patch` | Surgical find-and-replace. `commit=False` defers the git commit for batching |\n| `vault_commit` | Flush pending `commit=False` writes into one git commit |\n| `capture_lesson` | Capture lessons inline / batch-extract from text / look up existing lessons by keyword (`find=`) |\n| `session_briefing` | Tasks + lessons + git log + health in one call |\n| `delegate_task` | Route tasks to cheaper models or summarize vault files |\n| `worker_status` | Budget, connectivity, available models |\n\nPlus 5 [resources](https://mlorentedev.github.io/hive/reference/resources/) and 4 [prompts](https://mlorentedev.github.io/hive/guides/prompts/) for guided workflows.\n\n### Lesson reinforcement\n\nEvery read of a lesson via `vault_query`, `vault_search`, or `capture_lesson(find=…)` increments a counter and grows that lesson's confidence asymptotically toward 1.0. Validated lessons rank higher than one-shot captures over time.\n\n```bash\n# Surface the top-ranked lessons matching a keyword\ncapture_lesson(project=\"hive\", find=\"multi-process\")\n\n# Search lessons ranked by usage signal (not BM25)\nvault_search(query=\"timeout\", rank_by=\"reinforcements\")    # most-reinforced first\nvault_search(query=\"timeout\", rank_by=\"confidence\")        # highest decayed confidence\nvault_search(query=\"timeout\", rank_by=\"hybrid\")            # α=0.7 BM25 + 0.3 confidence\n```\n\nStorage: SQLite side-table at `HIVE_LESSON_DB_PATH` (default `~/.local/share/hive/lesson_reinforcement.db`). WAL mode + busy_timeout make it cross-process safe.\n\n## Architecture\n\n```\nMCP Host (Claude Code, Gemini CLI, Codex CLI, Cursor, ...)\n    └── hive-vault (MCP server, stdio)\n            ├── Vault Tools (7) ── Obsidian vault (Markdown + YAML frontmatter)\n            ├── Session Tools (1) ── Adaptive context assembly\n            └── Worker Tools (2) ── Ollama (free) → OpenRouter free → paid ($1/mo cap) → reject\n```\n\n## Documentation\n\nFull documentation at **[mlorentedev.github.io/hive](https://mlorentedev.github.io/hive/)**:\n\n- [Getting Started](https://mlorentedev.github.io/hive/getting-started/) — install for all MCP clients\n- [Configuration](https://mlorentedev.github.io/hive/configuration/) — all 19 environment variables\n- [Vault Structure](https://mlorentedev.github.io/hive/guides/vault-structure/) — how to organize your vault\n- [Use Cases](https://mlorentedev.github.io/hive/guides/use-cases/) — real-world workflows\n- [Architecture](https://mlorentedev.github.io/hive/reference/architecture/) — module map and design decisions\n- [Troubleshooting](https://mlorentedev.github.io/hive/guides/troubleshooting/) — common issues and fixes\n\nProject-bound knowledge (docs-as-code) lives in [`docs/`](docs/):\n\n- [`docs/adr/`](docs/adr/) — Architecture Decision Records\n- [`docs/runbooks/`](docs/runbooks/) — operational procedures\n- [`docs/troubleshooting/`](docs/troubleshooting/) — known issues and root-cause write-ups\n- [`docs/lessons.md`](docs/lessons.md) — accumulated gotchas and post-mortems\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup and PR workflow.\n\n```bash\ngit clone https://github.com/mlorentedev/hive.git \u0026\u0026 cd hive\nmake install   # create venv + install deps\nmake check     # lint + typecheck + test (478 tests, 90% coverage)\n```\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlorentedev%2Fhive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlorentedev%2Fhive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlorentedev%2Fhive/lists"}