{"id":"d719ef05-6825-4491-a3cc-458724e2f1b8","slug":"agentroots","kind":"mcp","name":"agentroots","summary":"Evidence-governed continuity for AI agents. Different agents. Same roots.","owner":"shanmukha-here","repoUrl":"https://github.com/shanmukha-here/agentroots","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-04T22:08:20.000Z","addedAt":"2026-10-21T09:27:04.352Z","logoUrl":"https://avatars.githubusercontent.com/u/32880753?u=91bd205a65a32f85ba4f7d39ab9d0527061f8034&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["databases","memory-knowledge"],"tags":["agent-memory","ai-agents","codex","deepseek","provenance","research-tools","sqlite"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T16:13:11.851Z","sample":false,"url":"https://conduits.dev/tools/agentroots","language":"Python","transports":["stdio"],"install":{"pypi":"agentroots"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"![\"AgentRoots](\"docs/assets/brand/agentroots-mark.svg\")
\n\n# AgentRoots\n\n### Different agents. Same roots.\n\nShared, evidence-backed project knowledge across agents, sessions, and harnesses.\n\nBuilt by Shanmukha Vellamcheti and Codex, an AI coding collaborator.\n\n
\n\nYour next agent should inherit the work, not repeat the investigation. AgentRoots keeps what\nyou tried, what you know, why it matters, and what remains to do in one durable project graph.\nA fresh agent gets compact, relevant pointers and opens the evidence only when needed.\n\n**Past attempts. Present understanding. Future intent. One project's shared roots.**\n\n\n\nAgentRoots is a local-first, open-source MCP server for engineering, research, and long-running\nagent work. A smaller agent can investigate and propose findings; another agent can review and\nreuse them later. Optional, read-only conversation backfill also recovers leads that never made\nit into a handoff or source file. History stays untrusted until conclusions pass review.\n\nNo required model API, cloud account, or agent orchestrator. Works with one agent across sessions\nor several agents sharing a project. It helps reduce repeated exploration, not eliminate every\nfile read or replace verification.\n\n## Start here\n\nRequires Python 3.11+ and Git. Use a Python virtual environment if your OS manages its Python\ninstallation. Codex proactive hooks also require Node.js.\n\n```bash\npython -m pip install \"agentroots @ git+https://github.com/shanmukha-here/agentroots.git@v0.2.0\"\nagentroots setup\n```\n\nSetup detects supported clients, asks before changing their configuration, and separately asks\nwhether it may read existing conversations. You can decline history or select particular projects.\nCodex requires an additional `/hooks` review. Downloads and approved backfill continue in the\nbackground; lexical search works while the semantic model warms up. Setup is short, but installation\nand large history imports depend on your connection and machine.\n\nThen use your agents normally. On supported hook paths, AgentRoots recalls compact project context\nat prompt and tool boundaries and queues new findings for review. It stays quiet when there is\nnothing useful to add. Notification presentation depends on the host; not every client shows toasts.\n\n```bash\nagentroots status # backends, RAM, storage, and indexing progress\nagentroots doctor # configuration and integration checks\nagentroots project-current # the project this checkout resolves to\n```\n\n**v0.2.0 is an alpha, not a universal background-memory service.** Codex has a validated MCP and\nproactive hook path. OpenCode automation is experimental. Claude and other stdio MCP clients can\ncall tools, but do not get automatic hooks from this package. DeepSeek support depends on its\nharness, not its model name. See the [support matrix](docs/support-matrix.md).\n\nNo PyPI publication yet. Existing users: see the [upgrade notes](CHANGELOG.md#upgrading-from-010).\nFor manual configuration and history selection, see [integrations](docs/integrations.md).\n\n## See the knowledge, not just the conversation\n\n\n\nThe same versioned state agents query becomes an offline, interactive knowledge map for humans.\nSearch, filter, trace relationships, inspect evidence, and copy record IDs to request corrections.\nThe synthetic overview covers all 14 record types and 12 relationship types. It contains no private\nproject content. Direct editing in the graph is planned; today corrections use the CLI or MCP.\n\n```bash\nagentroots graph PROJECT_ID /path/outside/repo/project-map.html\n```\n\n## Why I built AgentRoots\n\nMy research involves exploring many hypotheses and experimental paths. Coding agents let me try\nmore of them, faster. But as experiments, conversations, and subagents multiplied, keeping track\nof what we had already learned became its own problem.\n\nAn orchestrator might read a codebase to plan two tasks, then both subagents read the same files\nto get up to speed. That is the same understanding reconstructed three times. Weeks later, after\ncompaction or a switch to another harness, an agent can suggest an experiment we already discussed\nand ruled out. The reason may exist only in an old conversation, not in the code or latest handoff.\n\nI wanted that work to become durable without filling every new prompt with the entire past.\nAgentRoots connects the project's origin and intent, previous attempts, current evidence, and open\nquestions. An agent can inherit that understanding, check what matters for its task, and add to it.\nResearch motivated it, but the same problem appears in software projects and other long-running work.\n\nThis is not a claim that other memory tools only remember the past. Memory, planning, and provenance\nsystems overlap. AgentRoots focuses on connecting them in a compact, reviewable project graph,\nwithout owning the agents themselves. See the [landscape and boundaries](docs/landscape.md).\n\n## How the roots grow\n\n1. **Capture leads.** Agents propose records, or approved conversation history is indexed read-only.\n Background extraction creates candidates, never accepted facts.\n2. **Ground and review.** Link evidence, inspect contradictions, and accept or reject a proposal.\n A creator cannot accept its own proposal by default. Changes append revisions and events.\n3. **Recall when relevant.** MCP provides bounded context. Supported hooks also check emerging\n tool intent and results, not just the initial user prompt. They offer advice, not execution gates.\n4. **Keep state current.** Revalidate Git and tracker evidence, mark changed findings stale, and\n preserve failed approaches. Accepted results can explicitly resolve goals or questions.\n\nThe durable boundary is the **project**, not the agent, model, harness, or conversation. Routing\nuses explicit metadata, Git remotes, and registered aliases. Conversation text cannot choose a\ndifferent project. Bind a preferred project name once when needed:\n\n```bash\nagentroots project-bind PROJECT_ID /path/to/repository\n```\n\nMatching project identities does not automatically synchronize separate machines. Share approved\nstate through export/import or backup/restore; hosted team sync is not shipped.\n\n## Small context, inspectable evidence\n\nThe default MCP context response offers up to five matches within a conservative **200 estimated\ntoken** budget, with short record IDs for opening details. Hook injections are capped at **180\nestimated tokens**. These are payload budgets, not guarantees about a host's wrapper tokens,\ntotal turn cost, or provider cache hits. Changing hook context is appended at supported event\nboundaries, not rewritten into a stable system-prompt prefix.\n\n```json\n{\"tool\":\"research_get_context\",\"arguments\":{\"project\":\"my-project\",\"query\":\"previous cache failures\"}}\n{\"tool\":\"research_get_record\",\"arguments\":{\"project\":\"my-project\",\"record_id\":\"8f2a91c4\"}}\n```\n\nThe record ID above is illustrative. Use an ID returned by your context response. Full packets are\navailable with `view: \"full\"`; records are normalized and the serialized response is budgeted.\nMCP reads do not write packet-audit rows. Explicit CLI context packets are audited.\n\nRetrieval and extraction do different jobs:\n\n- **BGE + FTS5 + fuzzy search** retrieve existing state. BGE is enabled by default and warms in\n the background. FTS continues serving cold or failed-model requests. Set\n `AGENTROOTS_SEMANTIC=off` for lexical-only operation.\n- **Candidate extraction** uses configured Qwen first, optional GLiNER next, and a conservative\n heuristic otherwise. Qwen weights are not bundled, training is not required for normal use,\n and no extraction backend bypasses review.\n\nSee [measured latency, token costs, and limitations](docs/hook-evaluation.md). Development results\nare not evidence of universal productivity gains or reliable recall for every project.\n\n## What ships\n\n- External SQLite WAL storage, append-only events, revisions, and project-scoped graph queries.\n- Candidate review, evidence classification, contradictions, failure recall, and stale-state checks.\n- Read-only history backfill for Codex and OpenCode, with separate untrusted episode search.\n- Codex proactive hooks, a resident local daemon, and an experimental OpenCode plugin.\n- Read-only MLflow run search, comparison, snapshots, and revalidation. Trackio has an adapter\n interface; H-E-F and signac have importers.\n- Interactive read-only graph export, JSONL event transfer, and full-state backup/restore.\n- CLI, 16 MCP tools, resources, schemas, reproducible synthetic workflows, and regression tests.\n\nThe `research_*` tool names retain the original investigative ontology. The project boundary is\nbroad enough for engineering and general agent work; you do not need to invent a hypothesis or\npretend an exploratory run was preregistered. See the [protocol](docs/specification.md) and\n[tool configuration](docs/integrations.md).\n\n## Privacy and trust boundaries\n\nState, model weights, and indexes stay in OS user data/cache directories, not your repository.\nLarge artifacts stay in their tracker or original storage. Source conversations are read-only;\nbackfill requires approval. No telemetry or required cloud inference is built in.\n\nStored text is untrusted. Secret scanning and redaction reduce exposure but are not a guarantee\nthat every secret or prompt injection is detected. Claims, findings, observations, and decisions\nneed mechanically verified evidence before acceptance. A checksum verifies the referenced bytes,\nnot the scientific truth of a conclusion. Arbitrary URIs and caller-written test receipts are\nreferences, not automatically verified proof.\n\nActor names are local provenance labels, not authenticated identities. Self-review rules prevent\ncooperative mistakes, not hostile impersonation. AgentRoots does not expose a production team\nauthorization boundary. See [SECURITY.md](SECURITY.md).\n\nAgentRoots never owns agent spawning, model routing, stored-command execution, schedulers,\ntraining jobs, worktrees, or artifact storage. PostgreSQL, remote HTTP, ACLs, full Flowcept/AiiDA\nintegrations, and direct graph editing remain [roadmap work](docs/roadmap.md).\n\n## Contribute or reproduce the workflow\n\n```bash\npython -m pip install -e \".[dev]\"\npython -m pytest\npython -m examples.full_flow_demo --output /path/outside/repo/agentroots-demo\n```\n\nThe demo exercises approved synthetic history, review, a local MLflow fixture, duplicate-risk\nrecall, and Git-induced staleness. It is a reproducible core workflow, not a recording of a live\nagent. The polished live-session video is still pending.\n\n[Architecture](docs/architecture.md) · [Evaluation](docs/evaluation.md) ·\n[Changelog](CHANGELOG.md) · [Contributors](CONTRIBUTORS.md)\n\nApache-2.0. Contributions and reports from real projects are welcome.\n"}