{"id":50551896,"url":"https://github.com/vectifyai/condb","last_synced_at":"2026-06-04T04:03:10.439Z","repository":{"id":348223781,"uuid":"1133215890","full_name":"VectifyAI/ConDB","owner":"VectifyAI","description":"ConDB: The KV-Cache Native Context Database","archived":false,"fork":false,"pushed_at":"2026-05-26T16:28:22.000Z","size":9374,"stargazers_count":27,"open_issues_count":0,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T18:19:27.856Z","etag":null,"topics":["agents","ai","context-database","kv-cache","llm","long-context","rag","reasoning","retrieval","tree-search"],"latest_commit_sha":null,"homepage":"https://pageindex.ai","language":"Python","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/VectifyAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-13T03:28:26.000Z","updated_at":"2026-05-26T16:28:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/VectifyAI/ConDB","commit_stats":null,"previous_names":["vectifyai/condb"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/VectifyAI/ConDB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VectifyAI%2FConDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VectifyAI%2FConDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VectifyAI%2FConDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VectifyAI%2FConDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VectifyAI","download_url":"https://codeload.github.com/VectifyAI/ConDB/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VectifyAI%2FConDB/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33888302,"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-04T02:00:06.755Z","response_time":64,"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":["agents","ai","context-database","kv-cache","llm","long-context","rag","reasoning","retrieval","tree-search"],"created_at":"2026-06-04T04:03:09.699Z","updated_at":"2026-06-04T04:03:10.421Z","avatar_url":"https://github.com/VectifyAI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://docs.pageindex.ai/images/condb.png\" alt=\"ConDB Banner\" /\u003e\n\n\u003cbr/\u003e\n\n# ConDB: The KV-Cache Native Context Database\n\n\u003cp align=\"center\"\u003e\u003ci\u003eA new context database for reasoning-driven retrieval via tree search.\u003cbr/\u003e\nFast, context-aware retrieval at scale with up to 70% less token cost.\u003c/i\u003e\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n## 🌲 What is ConDB?\n\n**ConDB** (Context Database) is a tree-structured context database that uses LLM-powered **reasoning-based retrieval** via tree search instead of vector similarity — no vector DB, no chunking. It accepts [PageIndex](https://github.com/VectifyAI/PageIndex)-compatible document trees, [ChatIndex](https://github.com/VectifyAI/ChatIndex) conversation trees, filesystem trees, and custom hierarchical JSON — with no runtime dependency on either. The LLM reasons over the tree, like a human expert using a table of contents, to locate relevant content.\n\n### Why not vector search?\n\n- **Similarity ≠ relevance** — vector search retrieves what looks similar, not what is truly relevant. Similar-looking chunks may differ in intent (low accuracy), while truly relevant information may be expressed in very different language and get missed entirely (low recall). True relevance requires reasoning\n- **Chunking breaks semantic continuity** — documents must be split into fixed-size segments to fit embedding models, causing context fragmentation that destroys their natural structure and cross-section relationships\n- **Retrieval is blind to context** — embedding models encode the query alone, ignoring conversational history, user intent, and other contextual signals\n\nConDB replaces this with **reasoning-based tree search**: the LLM performs node-level relevance classification over a hierarchical index, incorporating full context — making retrieval adaptive, explainable, and traceable.\n\n### What makes ConDB different\n\n- **Fast tree search at scale** — reasoning-driven tree search with block partitioning and parallel processing, supporting complex, context-aware retrieval over large hierarchical structures\n- **KV-cache native** — the first database designed around LLM KV-cache reuse. By caching intermediate results during tree search, ConDB reduces token usage by up to 70% with no loss in accuracy. The same efficiency gains extend to memory systems for long-context reasoning at scale\n- **Unified long-context infrastructure** — a single system for both static and dynamic long-context workloads\n\n### Static long context\nStructured, persistent knowledge — documents (via [PageIndex](https://github.com/VectifyAI/PageIndex)), file systems, and codebases. Scalable retrieval within large, organized hierarchies.\n\n### Dynamic long context\nEvolving, runtime context — agent memory, long conversations (via [ChatIndex](https://github.com/VectifyAI/ChatIndex)), and autoresearch. Systems can continuously update, retrieve, and reason over newly generated information.\n\n### Key capabilities\n\n- **Hierarchical storage** — document trees, chat trees, and custom hierarchical JSON in SQLite\n- **Multiple retrieval strategies** — beam search for small trees, block retrieval for large documents\n- **Multi-provider LLM support** — Anthropic (Claude) and OpenAI (GPT) out of the box\n- **Extensible** — plug in custom storage backends, LLM providers, or retrieval strategies\n\n---\n\n## 🚀 Getting Started\n\n### Install\n\n```bash\npip install -r requirements.txt\n```\n\n### Basic Usage\n\n```python\nimport contextdb\n\n# Open database\ndb = contextdb.open(\"my_docs.sqlite\")\n\n# Configure LLM\ndb.set_llm(provider=\"anthropic\", model=\"claude-sonnet-4-6\")\n\n# Store a document tree\ntree_id = db.store(document_tree_json, format=\"document\")\n\n# Query with LLM reasoning\nresult = db.query(tree_id, \"What are the key findings?\")\nprint(result.contents)\n```\n\n### Index from files with an external tree builder\n\n```python\nfrom contextdb import ContextTree\n\ndef build_markdown_tree(path: str) -\u003e dict:\n    ...\n\nct = ContextTree(\"context.sqlite\")\n\ntree_id = ct.index_markdown_file(\"doc.md\", tree_builder=build_markdown_tree)\n\n# You can also generate a tree out of process and call:\n# tree_id = ct.index_document_tree(document_tree_json)\n\nct.close()\n```\n\n### Configuration\n\nCreate a `.env` file with your API keys:\n\n```\nANTHROPIC_API_KEY=sk-...\nOPENAI_API_KEY=sk-...\n```\n\nModel and provider settings live in `contextdb/config/config.yaml`:\n\n```yaml\nllm:\n  provider: anthropic          # anthropic or openai\n  model: claude-sonnet-4-6     # any model the provider supports\n  context_limit: 100000\n  max_concurrent: 10\n\nretriever:\n  beam_size: 3\n  max_turns: 5\n```\n\nOverride at runtime with environment variables:\n\n```bash\nLLM_MODEL=claude-opus-4-6 python your_script.py\n```\n\n---\n\n## 🔍 Retrieval Strategies\n\nConDB automatically selects the best retrieval strategy based on tree size:\n\n| Strategy | Best for | How it works |\n|----------|----------|--------------|\n| **Beam** | Small trees \u003cbr/\u003e (\u003c 50 nodes) | LLM evaluates and selects promising branches at each depth level |\n| **Block** | Large documents \u003cbr/\u003e (50+ nodes) | Splits tree into token-bounded blocks, LLM reasons over each block. KV-cache native — caches intermediate block results to cut token usage by up to 70% |\n\nYou can also specify a strategy explicitly:\n\n```python\nresult = db.query(tree_id, \"question\", strategy=\"block\", beam_size=3)\n```\n\n---\n\n## 📈 Benchmark Snapshot\n\nTwo benchmarks live under `bench/`.\n\n### Filesystem mode — SWEBench-FileTree\n\nRuns on [`AmuroEita/SWEBench-FileTree`](https://huggingface.co/datasets/AmuroEita/SWEBench-FileTree),\na path-only version of SWE-bench code retrieval:\n\n- 500 GitHub issues as queries\n- 475 `(repo, commit)` repository snapshots as independent retrieval universes\n- 58,058 file paths; no source code, no file summaries\n\nGiven an issue and one snapshot's file tree, return the file(s) the fix\ntouches. Specification: `notes/condb_swebench_filetree_bench.md`.\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\npython bench/run_swebench_filetree.py --tier medium\n```\n\nTiers (by retriever difficulty; lower difficulty = more path signal in query):\n\n```\neasy     107 queries   gold path appears in query text (sanity check)\nmedium   133 queries   gold filename appears in query    (main report)\nhard     261 queries   gold module stem appears          (fuzzy matching)\nall      500 queries   no filter, includes ~48% path-signal-less queries\n```\n\nOutput goes to `bench/runs/\u003ctimestamp\u003e__\u003ctier\u003e/`: `report.md`, `summary.json`,\n`per_query.jsonl`.\n\nBlock mode can optionally rerank only the cross-block merge candidates before\nthe file/directory split:\n\n```bash\npython bench/run_swebench_filetree.py --tier medium --strategy block --ranker vector\n```\n\nAvailable rankers are `none`, `bm25`, and `vector`. The vector ranker uses\nLiteLLM embeddings (`--embedding-provider`, `--embedding-model`) and leaves\nthe default `ranker=none` unchanged.\n\n#### Latest Run\n\nClaude Sonnet 4.6, `--ranker none`, 500 queries, 0 failures. The retriever\nreturns the file set it deems relevant — no fixed top-K cutoff. Metrics\ncompare the returned set against the gold set:\n\n- `precision = |returned ∩ gold| / |returned|`\n- `recall    = |returned ∩ gold| / |gold|`\n- `f1`, `exact_match` (set equality), `MRR` (rank of first hit)\n\nBlock (ConDB) is compared against a **Vertical baseline** — a per-beam\nvariant that expands each parent's children into separate subtree blocks\n(`A→B`, `A→C`), one LLM call per branch.\n\n| variant | precision | recall | F1 | exact_match | MRR | avg returned | avg latency |\n|---|---:|---:|---:|---:|---:|---:|---:|\n| Vertical (baseline) | 0.262 | 0.560 | 0.319 | 0.130 | 0.466 | 3.00 | ~24 s |\n| **Block (ConDB)** | **0.410** | **0.903** | **0.534** | 0.106 | **0.849** | 2.86 | ~8 s |\n\nBlock lifts recall from 0.56 to **0.90** at ~3× lower latency. Both runs\nreturn ~3 candidates per query against an `avg_gold = 1.24` — explaining\nthe low `exact_match`: the retrievers tend to return one extra plausible\nfile alongside the actual gold.\n\nBlock per-gold-count breakdown:\n\n| gold files | queries | precision | recall | F1 | exact_match | avg returned |\n|---|---:|---:|---:|---:|---:|---:|\n| 1 | 430 | 0.399 | 0.951 | 0.537 | 0.112 | 2.82 |\n| 2 | 48  | 0.469 | 0.677 | 0.544 | 0.062 | 3.12 |\n| 3 | 13  | 0.477 | 0.487 | 0.481 | 0.154 | 3.00 |\n| 4 | 6   | 0.581 | 0.500 | 0.532 | 0.000 | 3.50 |\n| 5 | 1   | 0.333 | 0.200 | 0.250 | 0.000 | 3.00 |\n| 6+ | 2  | 0.500 | 0.190 | 0.264 | 0.000 | 3.00 |\n\nReproduce:\n\n```bash\npython bench/run_swebench_filetree.py --tier all --strategy block    --ranker none\npython bench/run_swebench_filetree.py --tier all --strategy vertical --ranker none\n```\n\n### Document mode — single long document\n\nCompares retriever algorithms (Block / Beam / Vertical / ...) on one\nhierarchical document. Reports time, LLM calls, token usage with prompt\ncaching, and USD cost.\n\n```bash\npython bench/run_document_bench.py \\\n  --doc examples/large_doc.json \\\n  --config bench/queries.json\n```\n\nQueries live in the config JSON as `{\"queries\": [\"...\", \"...\"]}`. Swap in\nany `--doc` and any `--config` to benchmark a different document.\n\n---\n\n## 🧩 Learn More\n\n### Architecture\n\n```\ncontextdb/\n├── api/\n│   ├── condb.py          # ConDB — main entry point\n│   └── context_tree.py   # ContextTree — tree indexing + query API\n├── core/\n│   └── storage.py        # TreeDB (SQLite), StorageProtocol\n├── adapter/\n│   └── base.py           # DocumentTree, ChatIndex, Generic adapters\n├── retriever/\n│   ├── base.py           # Retriever protocols\n│   └── algorithm/        # Beam, Block retrieval strategies\n├── llm.py                # LLMClient (Anthropic, OpenAI)\n├── config/               # YAML configs for retrievers\n└── prompts/              # Jinja2 prompt templates\n```\n\n### Extending\n\n**Custom Storage Backend**\n\n```python\nfrom contextdb import StorageProtocol\n\nclass MyStorage:\n    def get_node(self, tree_id, node_id): ...\n    def get_children(self, tree_id, node_id): ...\n    # implement StorageProtocol methods\n\nct = ContextTree(storage=MyStorage())\n```\n\n**Custom LLM Provider**\n\n```python\nfrom contextdb import LLMProtocol\n\nclass MyLLM:\n    def chat(self, messages, system=\"\", tools=None):\n        return {\"content\": [...], \"stop_reason\": \"...\"}\n\nct = ContextTree(\"db.sqlite\", llm=MyLLM())\n```\n\n### Testing\n\n```bash\n./run_tests.sh all\n```\n\n---\n\n## 💬 Community\n\n### Related Projects\n\n- [**PageIndex**](https://github.com/VectifyAI/PageIndex) — vectorless, reasoning-based RAG that builds hierarchical tree indexes from long documents\n- [**ChatIndex**](https://github.com/VectifyAI/ChatIndex) — tree indexing for long conversations, enabling reasoning-based retrieval over chat histories\n- [**AgentFS**](https://github.com/anthropics/agentfs) — filesystem for AI agents\n\n### Connect with Us\n\n[![Twitter](https://img.shields.io/badge/Twitter-000000?style=for-the-badge\u0026logo=x\u0026logoColor=white)](https://x.com/PageIndexAI)\u0026ensp;\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white)](https://www.linkedin.com/company/vectify-ai/)\u0026ensp;\n[![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge\u0026logo=discord\u0026logoColor=white)](https://discord.com/invite/VuXuf29EUj)\u0026ensp;\n[![Contact Us](https://img.shields.io/badge/Contact_Us-3B82F6?style=for-the-badge\u0026logo=envelope\u0026logoColor=white)](https://ii2abc2jejf.typeform.com/to/tK3AXl8T)\n\n---\n\nLicensed under [Apache 2.0](LICENSE).\n\n© 2026 [Vectify AI](https://vectify.ai)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvectifyai%2Fcondb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvectifyai%2Fcondb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvectifyai%2Fcondb/lists"}