Agentic Rag

Long-term memory for Claude Code — in a real database, filled by your own sessions.

Claude forgets everything when a session ends. agentic-rag gives it a memory that lasts — a durable, searchable knowledge base in local PostgreSQL + pgvector — and fills that memory from the Claude sessions you already run. Hybrid vector + full-text search over a curated knowledge graph, on your machine and your own Anthropic account. No cloud service, no third-party RAG in the loop, no hosted memory to rent.

License: MIT version Python 3.13 tests PostgreSQL + pgvector Claude Code

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 your own Claude sessions. You don't curate a corpus by hand; the work you already do becomes the knowledge base.

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 a single transaction. Search then fuses vector similarity and full-text into one ranked list. And when a session ends, a single-writer worker reads the transcript with your claude CLI and turns what you learned — the lessons, the decisions, the gotchas — into durable, findable memories, deduped on the way in.

It runs entirely on your machine and on your own Anthropic account — whatever your local claude CLI is logged in with, a Claude subscription or your own ANTHROPIC_API_KEY; the choice is yours. Embeddings are always local (Ollama), so retrieval costs nothing either way. It's RAM-lean by design: no always-on daemon beyond Postgres and Ollama, and an idle footprint near zero between sessions. 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.

Your data stays yours. This repository is code only — it ships no content. Your documents, embeddings, links, and any secrets live in your PostgreSQL database on your machine; nothing leaves it unless you explicitly configure a synced backup directory. The LLM calls that mine and curate your memory run through your local claude CLI on your own Anthropic account — never a third-party RAG service.

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 mines your Claude sessions into durable knowledge. When a session ends, the transcript is queued and a worker uses your claude CLI to extract the lessons and decisions worth keeping — saved as findable memories, not left to rot in a log. This is the headline feature.

♻️ 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. Everything lives in your Postgres. LLM-assisted work runs through your local claude CLI on whatever auth you gave it — a Claude subscription or your own ANTHROPIC_API_KEY, your call. Embeddings are always local (Ollama), so search and retrieval cost nothing regardless. On a subscription, mining and curation add nothing beyond your plan.

⚡ RAM-lean. A single-writer worker (flock singleton), no long-lived daemon of its own. Between sessions the footprint is essentially Postgres + Ollama idling — nothing else.

---

Quick start

agentic-rag is a rag command-line tool plus two MCP servers that wire into Claude Code.

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).
• The claude CLI, authenticated for claude -p — with a Claude subscription (OAuth login) or an ANTHROPIC_API_KEY, whichever you prefer. agentic-rag uses whatever the CLI is set up with.
• uv and Python ≥ 3.13.

Install, in order:

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          # registers the MCP servers + hooks; schedules the backup job (macOS)

• 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 registers the agentic-rag (read-write) and agentic-rag-ro (read-only, for subagents) MCP servers with claude and merges three session hooks into ~/.claude/settings.json. On macOS it also auto-schedules the nightly backup job via launchd (the maintenance job is enabled separately with rag maintenance --install-launchd); on Linux scheduling is skipped — see docs/deploy/scheduling-linux.md for cron/systemd recipes.

Restart Claude Code afterward so it picks up the new servers and hooks. Then just work — the hooks inject relevant memory at session start, recall on your prompts, and queue each finished session for mining. For humans there's 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

---

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 Claude Code session ends, a Stop hook enqueues the transcript. A single-writer worker drains the queue and runs claude -p — on whatever your claude CLI is authenticated with — to pull out the durable memories, lessons, and signals from what you just did, each one saved through the write gateway behind a near-duplicate gate. A fix you discovered today becomes something Claude can recall tomorrow, 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.

---

How it works

   Your Claude sessions                     rag save · migrate import · MCP write tools
   (queued & mined on session end)          (you, or an agent)
            │                                               │
            └───────────────────┬───────────────────────────┘
                                │
                    one audited write gateway
       strips secret-shaped tokens · chunks + embeds (local Ollama) · resolves edges · logs
                                │
                ┌───────────────┴────────────────┐
        PostgreSQL + pgvector              typed knowledge graph
        documents · chunks halfvec(1024)   edges: references · extends · …
        HNSW ANN  +  EN/DE full-text
                                │
                one hybrid ranked search  ──  vector ⊕ full-text
                                │
   session-start context · prompt-time recall · read-only MCP behind a privilege boundary

• Your own Anthropic account. Every LLM call goes through the local claude command, using whatever auth you gave it — a Claude subscription or your own ANTHROPIC_API_KEY. On a subscription those calls add nothing beyond your plan; with a key they're metered by Anthropic like any API use — your choice, either way. Embeddings never leave the box (local Ollama), so retrieval is free regardless of auth.
• One audited write path. Every change — a manual save, a mined memory, an import — funnels through a single gateway that strips secret-shaped tokens, regenerates chunks + embeddings in one transaction, resolves dangling edges, and writes an audit row. Embeddings fail open (queued for retry if Ollama is down); nothing else does.
• Least privilege, by role. Three login roles enforce a destruction-protection matrix: rag_reader (SELECT only, used by search and the read-only MCP), rag_writer (INSERT/UPDATE but no DELETE/TRUNCATE/DROP), and rag_admin (migrate, purge, restore).
• It steps aside, not in front. If Ollama is down, search degrades to full-text-only and returns a warning rather than failing; the maintenance job always exits 0.

The full story is in the handbook — the mental model, everyday use, configuration, importing an existing wiki, and the architecture and design rationale.

---

Comparison

agentic-rag sits between two worlds: the file-based LLM-Wiki family (human-readable Markdown with a lint/graph layer) and typical RAG stacks (hosted or API-driven retrieval you feed documents to). Every cell below is marked honestly — including the rows where each of them beats us.

Legend: ✅ shipped & live · ⚠️ partial / caveated · ❌ absent

vs LLM-Wiki systems (file-based knowledge wikis)

Capability	agentic-rag	File-based LLM-Wiki
Hybrid vector + full-text ranked search (ANN at scale)	✅	⚠️ lexical/graph, file-scan
Bilingual full-text (EN + DE) + semantic recall	✅	⚠️
Transactional, audited writes through one gateway	✅	⚠️
Scales to a large corpus (HNSW index)	✅	⚠️ file-scan slows
Human-readable, git-diffable plain-text store	⚠️ import/export MD; store is Postgres	✅
Zero-infrastructure (no DB/service to run)	❌ needs Postgres + Ollama	✅
Imports an existing llm-wiki store	✅ rag migrate	✅ it is one

Bottom line: if you want a git-tracked pile of Markdown, a file-wiki wins on its home turf. If you want fast hybrid recall over a growing corpus with transactional safety, agentic-rag wins — and it can import your existing llm-wiki to get you there.

vs typical RAG systems (retrieval frameworks / hosted memory)

Capability	agentic-rag	Typical RAG stack
Local-first — runs on your own Anthropic account, no third-party RAG service in the loop ¹	✅	⚠️ usually a hosted service
Auto-populates from your own Claude sessions (mining)	✅	❌ you feed it
Self-curation (dedup, near-dup gate, refute/archive)	✅	⚠️
Typed knowledge graph (edges) alongside vector search	✅	⚠️
One audited write gateway with secret stripping	✅	❌
Read/write privilege boundary for subagents (RO MCP)	✅	⚠️
Turnkey managed hosting / large ecosystem ²	⚠️ self-host, young	✅

Bottom line: a hosted RAG stack wins on turnkey scale and ecosystem. agentic-rag wins on being local-first, running on your own Anthropic account with no third-party service in the loop, self-populating-from-your-own-work, and self-curating — a memory that fills and tidies itself instead of one you have to keep feeding.

_{¹ agentic-rag is auth-agnostic: its LLM-assisted mining and curation call your local claude CLI on whatever you gave it — a Claude subscription (no extra cost beyond your plan) or your own ANTHROPIC_API_KEY (metered by Anthropic, your choice). Either way embeddings are always local (Ollama), so retrieval is free, and there's no third-party RAG service between you and your data. Most hosted RAG stacks route your documents through a paid service.
² agentic-rag is newly public and self-hosted — the field's clearest edge over us is turnkey managed hosting and a large plugin/integration ecosystem.}

---

Configuration

Config lives in one TOML file at ~/.agentic-rag/config.toml. Every key is optional — omit a section to keep its defaults.

Setting	Default	What it does
[db] name	agentic_rag	Database name.
[db] host	"" (local socket)	Empty = local unix socket; set it for a networked/remote server.
[embed] model	bge-m3	Ollama embedding model tag.
[embed] dim	1024	Fixed to the schema (halfvec(1024)); init-db refuses a mismatch.
[ollama] url	http://localhost:11434	Local Ollama endpoint.
[backup] local_dir	~/.agentic-rag/backups	Where pg_dump archives are written.
[backup] cloud_dir	— (unset)	Opt-in copy to a synced/cloud directory; unset = local-only, nothing leaves the machine.
[pg] bin_dir	auto-resolved	Only needed if pg_dump/pg_restore/psql aren't on PATH (e.g. Postgres.app).

Roles are created passwordless by default, relying on local peer/trust auth (Postgres and agentic-rag on the same machine). For a networked or shared instance, set role passwords with ALTER ROLE … and let libpq authenticate via ~/.pgpass or PGHOST/PGPORT/PGPASSWORD — see the handbook's privacy chapter.

---

📖 Documentation / Handbook

The full story lives in the agentic-rag Handbook — a single, progressively-ordered read from the mental model through everyday use, configuration, importing, and the engine's architecture and design rationale. A few key chapters:

• Understand — What is agentic-rag? · The mental model
• Use — Quick start · Working with your memory · Session mining & curation
• Configure — Privacy, cost & control
• Develop — Architecture · Reference — CLI & MCP

Start at the handbook index for the one-line "what you'll learn" map of every chapter.

---

Status

agentic-rag is young but solid — a real engine, openly developed. What's live today:

• ✅ Storage & search: PostgreSQL + pgvector schema, HNSW ANN blended with EN/DE full-text into one ranked list, the typed edge graph, the three-role destruction-protection matrix.
• ✅ The write gateway: secret stripping (in and out), one-transaction chunk + embed + edge-resolve + audit, embeddings that fail open with a retry queue.
• ✅ Session mining: the hooks → queue → single-writer worker → claude -p → gateway loop, with a near-duplicate gate, on whatever auth your claude CLI carries.
• ✅ Curation & safety: rag review, refute-as-archive, and admin-only rag purge (removes only already-refuted documents, as rag_admin).
• ✅ Maintenance & backups: pg_dump backups with rotation, the tiny always-exit-0 maintenance job, and the weekly report-only restore-test. macOS auto-schedules via launchd; Linux uses the documented cron/systemd recipes.
• ✅ Claude integration: two user-scope MCP servers (read-write + a read-only server behind a privilege boundary for subagents), idempotent install that preserves foreign hooks.
• ✅ Quality: 316 passing tests and a content-free repository.

The clearest gap relative to the field is maturity: it's newly public and self-hosted, without the turnkey hosting or large ecosystem of established RAG stacks.

---

Acknowledgments

agentic-rag builds on other people's ideas and tools:

• Andrej Karpathy — the LLM-Wiki idea that shaped the durable-knowledge model this import path speaks to.
• The llm-wiki format — topic-partitioned Markdown with an optional memory store; rag migrate imports it wholesale, so an existing wiki carries straight over.
• pgvector and Ollama (bge-m3) — the local vector search and embeddings underneath everything.
• Anthropic — Claude Code, its hooks, and the MCP integration agentic-rag plugs into.

---

Contributing

Tests come first (TDD), and docs/ is kept in step with the code. A warn-only doc-reminder hook ships under .githooks/: if a commit touches agentic_rag/ or sql/ without touching docs/, it prints a reminder — it never blocks. Enable it once per clone:

git config core.hooksPath .githooks

Run the suite with uv run pytest. See the handbook's Contributing chapter for dev setup, the test database, and code layout.

License

MIT. The repository is code-only and content-free — your documents, embeddings, and config stay in your own PostgreSQL database, on your own machine.