agentic-rag MCP server

agentic-rag

Provider-neutral long-term memory and compaction continuity — in a real database.

Coding sessions end and long contexts compact. agentic-rag preserves both: a canonical, searchable knowledge base in local PostgreSQL + pgvector, plus bounded checkpoints that let Claude Code, Codex, and Antigravity resume after compaction. Hybrid vector + full-text search, lifecycle hooks, and a provider CLI you control — without a hosted RAG service.

0.6.34 dashboard refresh: clearer grouped navigation, consistent cards, tables and status badges, readable narrow-screen layouts and improved text contrast in the sampled synthetic administrator views. Behavior, permissions and stored data are unchanged; see the dashboard reference.

0.6.33 embedding comparison: optional task prefixes preserve model-bound generation identities. The local BGE/Jina CPU results recommend retaining BGE; Nano has faster model calls but mixed independent ranking, and Small exceeds the frozen budgets. Updating code selects no model and rewrites no vectors.

0.6.29 signed webhooks: explicitly subscribe to committed memory, review, source, lifecycle or owned ingestion-job changes. A separate local sender posts minimal signed notices with scoped authorization rechecks, bounded retries and stable event IDs. Capture starts off; upgrades configure no receiver and send nothing. Migration038 preserves existing knowledge and vectors. Use the webhook operations playbook.

0.6.28 scoped feedback: explicitly capture a search and label a result useful, not useful, the wrong source or missing expected evidence. Writers can revise and retract their own signals; feedback changes neither knowledge nor ranking. A local operator can approve a safe query for private, read-only failure evaluation. It is off by default and adds schema037 without rewriting existing data. Follow PB07101.

0.6.25 source-backed images: screenshots, receipts and scans can become reviewable knowledge. agentic-rag keeps the exact image in PostgreSQL, reads its text with a Tesseract you install yourself, and records where each word sits; an optional local Ollama model can describe the picture. Nothing is searchable before you confirm it against the original. It is off by default, adds migration036 without touching existing data, and calls no image engine during the upgrade. Follow the image playbook.

0.6.22 lexical search: selective full-text queries run expensive truth and lifecycle checks once per matching document, retaining the same scoped results and ranking. Generic vector plans continue past filtered nearest neighbours on pgvector0.8+, with an exact fallback when the scan cannot fill its candidate pool. Supported0.7 installations use that exact path. Truth and source checks remain before ranking and limits; retrieval settings restore on return. Service embedding preparation also retains worker priority and background timeout rules. Upgrade existing0.6.21 stores with the lexical-search upgrade procedure.

0.6.21 native source continuity: generated compaction summaries no longer become original user evidence. A bounded, audited quarantine repairs old source classification; migration033 preserves original records and ordinary no-revival rules. Use the source-origin upgrade gate before restarting capture. Native synthetic observations are published under the acceptance fixtures.

0.6.20 extraction policy: an operator can decide in one versioned file which mined knowledge is kept per domain or project: output categories, item and text limits, plus advisory guidance for the provider. Admitted work keeps its policy across retries, a change only affects new work, and without a file nothing changes. Upgrade with the operations playbook and read extraction policy.

0.6.19 memory lifecycle: an operator can mark one memory as a duplicate, extension, replaced version or contradiction of another after a read-only preview. The decision is a separate audited record: the memory itself, its evidence and its links stay untouched, search shows only the current one, and a correction makes it visible again. Automatic curation now merges only copies with the same title and type. Upgrade with the operations playbook and read memory lifecycle.

0.6.18 pattern synthesis: an operator can let a model suggest recurring patterns across at least three independent user reports in one domain and project. Each suggestion is stored as a reviewable inference with exact citations and disappears from every read as soon as a cited source changes. It is off by default; upgrade with the operations playbook and read pattern synthesis.

0.6.17 temporal search: searches can recognize yesterday/gestern, last week/letzte Woche, next month/nächsten Monat and explicit dates, then order or filter hits by their recorded event time without widening access or validity. It is off by default and needs no migration; read temporal search.

0.6.16 source evidence: every client can inspect the exact stored quotes, source trust, claim review and fact lifecycle behind a memory, and reviews are bound to the evidence version that was inspected. That release introduced schema029; follow its verified upgrade playbook and read claim evidence.

0.6.15 reranker Settings: administrators can select MiniLM L6 EN/DE, mMARCO DE/EN (default) or Jina tiny (English only). Its additive schema028 is included in the 0.6.16 upgrade; use the verified upgrade and model procedure. Knowledge and existing embeddings are preserved.

0.6.13 request tracing: metadata-only request IDs and authorized job diagnostics are available through the dashboard, REST and CLI. Read the tracing operations guide. Existing service stores introduced additive schema026; current startup requires030 as described above.

0.6.12 dashboard: authenticated setup, enrolled-client administration and scoped knowledge/source browsing, served by the same engine. Read the dashboard operations guide and access/limits reference. That release introduced the verified additive schema025 upgrade; standalone CLI/stdio operation remains available.

New in v0.6.0: ten retrieval and ingestion features, including original-backed entity aliases, bounded embedding reuse and offline confirmed-failure evaluation. Features 1–10 are adopted locally on schema 001–019. Read What’s New in 0.6.0 and the latest production acceptance.

0.5.0: Antigravity CLI (agy, Gemini) compaction continuity — rag install --agy, SessionStart/PreInvocation/Stop hooks, /compact handoff, automatic-compaction detection, Antigravity transcript mining. Read What’s New in 0.5.0.

0.4.0: Claude compaction continuity — six Claude hooks, the managed 1M/500K autoCompactWindow policy, the compact_summary handoff, and rag install --check/--restore. Read What’s New in 0.4.0.

0.3.0: Codex compaction continuity, native-memory policy, recoverable global installation, and provider-neutral mining. Read What’s New in 0.3.0.

Most "RAG memory" tools are a cloud retrieval layer you feed documents to: you push, you query, you pay per call. agentic-rag flips both halves. It stores knowledge in local Postgres + pgvector — real HNSW approximate-nearest-neighbour search blended with bilingual full-text — and it populates itself from supported coding sessions. It also stores compact, audited continuation checkpoints at Claude Code, Codex, and Antigravity compaction boundaries — on Claude including Claude's own compact summary as a bounded handoff.

Every content write funnels through one gateway: it strips secret-shaped tokens, chunks and embeds the text with a local model, resolves the document's links into a typed knowledge graph, and logs the change — all in one transaction. When a session ends, a single-writer worker uses the configured extraction provider to turn the bounded transcript digest into durable, findable memories. The core data model and provider seam are provider-neutral; integrations adapt each coding agent's lifecycle and output contracts.

It runs on your machine and uses your configured provider account for LLM-assisted mining, curation, and bounded checkpoint enrichment: Codex/Claude CLI authentication or an explicitly configured compatible HTTP endpoint. Mining prompts can also include all matching pin bodies; mining secret-strips the provider-bound copies without mutating stored pin text. Embeddings default to local Ollama. Selecting an external managed generation sends future search queries and semantic duplicate candidate title/body to its provider; explicit bounded builds send stored chunks. Default research skips structured assessment; its retrieval uses the selected embedding profile. Bounded research follows eligible entity aliases and up to three graph hops, with per-facet literal/semantic coverage and original-source paths. collects evidence for compound questions and reports disagreement or missing support; --provider explicitly enables configured-provider assessment. An optional local multilingual reranker can improve ambiguous-source ordering when its measured gains justify extra latency. The default installation adds no always-on daemon beyond Postgres and Ollama. Optional neural reranking uses a separate local model process with its measured budgets and configuration choices. And it's built data-safety-first — it archives rather than deletes, writes through a least-privilege role matrix, audits every change, and periodically restore-tests its own backups.

Bounded profiles include incremental thematic summaries: local original excerpts with source/version drill-down, trust/temporal invalidation and audited reuse. The additive017 cache preserves baseline reads on016. Paired measurements record compression, coverage and additional original-corpus query cost.

Entity identities and scoped aliases link confirmed alternate names to original facts. rag entity resolve retrieves original facts under confirmed alternate names; explicit source-backed links preserve scope/domain boundaries and support audited revocation. Existing exact-name search and assertion keys remain unchanged. PB-5.8 records the supported 017→018 upgrade and code recovery. Incremental ingestion reuses exact sanitized embedding inputs under a verified local model identity, with bounded preprocessing and ordered audited writes. Confirmed-failure evaluation compares offline routes and public mining prompts while retaining original evidence. The supported 018→019 upgrade and recovery are in PB-5.9; PB-5.10 covers evaluation and code-only adoption. Sealed benchmark candidates do not change production search or mining policy.

Your data stays under your control, with explicit provider calls. This repository is code only — it ships no content. The canonical store lives in your PostgreSQL database, but the configured extraction provider intentionally sends these provider inputs: mining sends a bounded, secret-stripped transcript digest, live domain names, and secret-stripped copies of all matching pin bodies without mutating stored pin text; curation sends selected stored documents and contradiction evidence; checkpoint enrichment sends a secret-stripped transcript delta and validates the returned checkpoint content before persistence. Explicit research provider mode sends a redacted question and selected bounded source excerpts; default research skips structured assessment; retrieval still uses the selected embedding profile. Optional managed provider profiles can send search queries and explicitly selected rebuild batches to their configured HTTP destination. Selecting an external generation also sends future semantic duplicate candidate title/body there. Inspection is offline; probes use fixed synthetic inputs. Optional synced backups copy data only to a directory you configure. agentic-rag has no separate hosted RAG backend.

Why · Quick start · What's different · How it works · Comparison · Configuration · 📖 Handbook · Status · Acknowledgments · License

---

Why agentic-rag

🔎 Hybrid search that actually ranks. Vector ANN over pgvector (HNSW, cosine) — multilingual by way of bge-m3 embeddings — blended with GIN keyword full-text into one ranked query. Search in any language; not a file scan, not lexical-only.

🌱 It turns sessions into durable knowledge and continuation state. Mining uses your configured extraction provider (Codex/Claude CLI or opt-in HTTP). On Claude Code and Codex, PreCompact also captures a fast checkpoint so SessionStart(source="compact") can restore the goal, blockers, next action, repository state, and evidence references; on Claude the checkpoint also carries Claude's compact summary.

♻️ It curates itself. A near-duplicate gate stops the store from bloating; rag review surfaces duplicates, dangling links, and stale pins; refuting a fact archives it (with a reason and evidence), never hard-deletes it.

🔒 Local-first, on your own account. Canonical knowledge and checkpoints live in your Postgres. Structured LLM work uses your configured CLI or opt-in HTTP provider. Embeddings default to local Ollama; external managed profiles receive queries, semantic duplicate candidates and explicit rebuild batches. Default research skips structured assessment; its retrieval uses the selected embedding profile.

⚡ RAM-lean. A single-writer worker (flock singleton), no long-lived daemon of its own. Without the optional reranker runtime, the between-session footprint is essentially Postgres + Ollama idling.

---

Quick start

OpenCode / DeepSeek: install the native RAG adapter on the execution host with uv run rag install --opencode. It supports startup context, selective recall, checkpoint/handoff and idle mining. For T3 on Windows, install on the Mac execution host; canonical context and a real read-only RAG tool call were verified through T3. See the documented limits.

agentic-rag is a rag command-line tool with provider integrations. The no-option install wires two MCP servers, six lifecycle hooks, and the managed compaction window into Claude Code; the explicit Codex and Antigravity (--agy) targets install continuity configuration and hooks.

Prerequisites:

• PostgreSQL 17 with the pgvector extension (the schema uses halfvec, pgvector ≥ 0.7).
• Ollama with the embedding model pulled — ollama pull bge-m3 (1024-dim, fixed to the schema).
• An authenticated LLM CLI: Codex (codex login) or Claude (claude -p). Claude/Haiku remains the package default for compatibility; select the provider in [llm].
• uv and Python ≥ 3.13.

Install the common foundation, then choose an integration:

uv sync
uv run rag init-db          # creates the DB + schema + roles, seeds the 'general' domain
uv run rag domain add programming --description "Software engineering notes"
uv run rag install --check  # preview the Claude settings merge; writes nothing
uv run rag install          # Claude MCP/hooks + macOS backup schedule; omit for Codex-only
uv run rag install --agy    # Antigravity CLI (agy) hooks.json target; --check previews

• rag init-db creates the database if needed, applies the migrations in sql/, creates the three least-privilege roles, and seeds the built-in general domain. Run it first — rag install does not create the database.
• rag domain add <name> adds any domains you want to organize documents under (general always exists; add more anytime).
• rag install --check previews the Claude merge (managed: autoCompactWindow=500000, the would-change path, policy warnings) and writes nothing.
• The no-option rag install is the Claude target: it registers the agentic-rag (read-write) and agentic-rag-ro (read-only) MCP servers, merges six hooks (SessionStart, UserPromptSubmit, Stop, PreCompact, PostCompact, SessionEnd) plus autoCompactWindow = 500000 into ~/.claude/settings.json, backs the file up to a unique settings.json.bak.<id>, and prints a rag install --restore <record> rollback command. On macOS it also schedules nightly backup; omit this command for a Codex-only setup.

If you ran the Claude target, hooks reload live; start a new Claude Code session so it picks up the MCP servers, then review the handlers with /hooks and confirm /autocompact reports 500000 tokens from settings. For humans the same store is available through the CLI:

rag save --title "Postgres VACUUM tuning" --domain programming \
    --dtype lesson --body "autovacuum_vacuum_scale_factor tradeoffs..."
rag search "vacuum tuning" --domain programming
rag get <slug-or-id>          # body + incoming/outgoing graph edges
rag status                    # counts, queue health, last backup/curation

For Codex continuity, preview before touching your user configuration, install, then inspect and trust the changed commands in Codex:

uv run rag install --codex --check
uv run rag install --codex
# Start Codex, run /hooks, inspect all six agentic-rag commands, then trust them.
uv run rag status

The Codex transaction manages only ~/.codex/config.toml, ~/.codex/hooks.json, and ~/.codex/compact_prompt.md. It prints every changed path, backup, validation result, and a ready-to-run rollback command:

uv run rag install --codex --restore /absolute/path/to/codex-rollback-<id>.json

Use the exact rollback-record pathname printed by the successful install. Check mode writes nothing. Repository support does not mean a particular machine has completed hook trust or live compaction verification; review /hooks and confirm rag status after every installation.

The Codex target never installs a scheduler. On a Codex-only macOS setup, use uv run rag backup --install-launchd for scheduled database backups; Linux uses the handbook's cron/systemd recipes.

---

What makes it different

Four things that, together, set it apart from both file-based knowledge wikis and hosted RAG stacks:

1. Real hybrid search over a curated graph

Documents are chunked and embedded into halfvec(1024) columns indexed with HNSW, and each chunk is embedded with the multilingual bge-m3 model — so semantic recall works in any language — and also carries generated tsvectors for English/German keyword full-text. A single query runs vector ANN and full-text together and returns one ranked list. Documents aren't an undifferentiated pile: they carry a type (concept, lesson, signal, synthesis, reference, …) and connect through a typed edge graph (references, extends, depends_on, supersedes, contradicts, …), so rag get shows you not just a document but its neighbourhood.

2. Automatic session-mining — the star feature

This is what makes agentic-rag feel like it grows rather than sits there. When a supported coding session ends, a lifecycle hook enqueues the transcript. A single-writer worker drains the queue and calls the configured extraction provider to pull out durable memories, lessons, and signals, each saved through the write gateway behind a near-duplicate gate. A fix you discovered today becomes something a future session can recall, with no "remember to write this down" step. It reads only your local session transcripts.

3. Knowledge domains you grow and curate

Domains are just data — a label for where to look (general is seeded at init). Add them with rag domain add, scope any search with --domain, and let the importer derive them from an existing store's topics. Curation is first-class: rag review reports near-duplicates, dangling links, and stale pins; refuting a fact archives it with a required reason + evidence; rag purge removes only already-refuted documents, and only as rag_admin.

4. Built-in maintenance, backup, and restore-testing

rag backup runs pg_dump -Fc locally (plus an optional copy to a synced directory you configure), with rotation. rag maintenance is a tiny, single-flight, always-exit-0 job that ticks the worker, rotates logs, and — weekly — runs a report-only restore-test: it restores your newest dump into an isolated scratch database, compares row counts, and drops it. A backup you've never restored isn't a backup; this one checks itself.

---