Metadata-Version: 2.4
Name: ragbrain
Version: 0.1.1
Summary: Bi-temporal RAG platform: cited, temporally-correct answers plus system-time replay. Self-hostable memory and audit layer for AI agents.
Project-URL: Homepage, https://github.com/Nagendhra-Madishetti/ragbrain
Project-URL: Repository, https://github.com/Nagendhra-Madishetti/ragbrain
Project-URL: Issues, https://github.com/Nagendhra-Madishetti/ragbrain/issues
Author-email: Nagendhra Madishetti <nagendhra405@gmail.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent-memory,ai-agents,audit,bitemporal,falsification,graphrag,grounding,hallucination-detection,knowledge-graph,llm,llm-memory,long-term-memory,mcp,memory,point-in-time,provenance,rag,retrieval-augmented-generation,semantic-search,temporal,temporal-knowledge-graph,vector-search
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <4,>=3.10
Provides-Extra: all
Requires-Dist: falkordb<2,>=1.0.10; extra == 'all'
Requires-Dist: graphiti-core==0.29.2; extra == 'all'
Requires-Dist: llama-index-core==0.14.23; extra == 'all'
Requires-Dist: llama-index-llms-openai-like<1,>=0.4; extra == 'all'
Requires-Dist: pypdf<6,>=4; extra == 'all'
Requires-Dist: pyyaml<7,>=6; extra == 'all'
Provides-Extra: backends
Requires-Dist: falkordb<2,>=1.0.10; extra == 'backends'
Requires-Dist: graphiti-core==0.29.2; extra == 'backends'
Provides-Extra: dev
Requires-Dist: fastapi<1,>=0.110; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mcp<2,>=1; extra == 'dev'
Requires-Dist: pypdf<6,>=4; extra == 'dev'
Requires-Dist: pytest<9,>=8; extra == 'dev'
Requires-Dist: pyyaml<7,>=6; extra == 'dev'
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
Requires-Dist: uvicorn<1,>=0.27; extra == 'dev'
Provides-Extra: documents
Requires-Dist: pypdf<6,>=4; extra == 'documents'
Provides-Extra: embeddings
Requires-Dist: flagembedding>=1.2; extra == 'embeddings'
Provides-Extra: falkordb
Requires-Dist: falkordb<2,>=1.0.10; extra == 'falkordb'
Provides-Extra: graphiti
Requires-Dist: graphiti-core==0.29.2; extra == 'graphiti'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core==0.14.23; extra == 'llamaindex'
Requires-Dist: llama-index-llms-openai-like<1,>=0.4; extra == 'llamaindex'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1; extra == 'mcp'
Provides-Extra: mineru
Requires-Dist: mineru; extra == 'mineru'
Provides-Extra: observability
Requires-Dist: langfuse<4,>=2; extra == 'observability'
Provides-Extra: okf
Requires-Dist: pyyaml<7,>=6; extra == 'okf'
Provides-Extra: reranker
Requires-Dist: flagembedding>=1.2; extra == 'reranker'
Provides-Extra: serve
Requires-Dist: fastapi<1,>=0.110; extra == 'serve'
Requires-Dist: python-multipart>=0.0.9; extra == 'serve'
Requires-Dist: uvicorn<1,>=0.27; extra == 'serve'
Description-Content-Type: text/markdown

<div align="center">

<img src="https://raw.githubusercontent.com/Nagendhra-Madishetti/ragbrain/main/docs/media/logo.png" alt="RAGBrain" width="300">


# RAGBrain

**The Open-Source Bi-Temporal RAG Framework for AI Agents. Prove what your AI knew, and when.**

RAGBrain is a **long-term memory and retrieval layer for LLM agents**. It pairs
retrieval-augmented generation with a **temporal knowledge graph**, so an agent can answer
what is true *now*, what was true *on any past date*, and what the system *believed at a past
moment* before a correction arrived.

Any document in, a cited and temporally-correct answer out, plus the capability the rest of
the field lacks: replay what the system believed at any past moment, without leaking later
corrections into the past.

`agent memory` · `LLM long-term memory` · `temporal knowledge graph` · `point-in-time queries`
· `GraphRAG` · `vector search` · `grounded answers` · `provenance and audit` · `MCP server`
· `self-hosted`

[![ci](https://github.com/Nagendhra-Madishetti/ragbrain/actions/workflows/ci.yml/badge.svg)](https://github.com/Nagendhra-Madishetti/ragbrain/actions/workflows/ci.yml)
[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)

[Quick start](#quick-start) ·
[Architecture](#architecture) ·
[Benchmarks](#benchmarks) ·
[API](#api) ·
[Documentation](#documentation)

</div>

---

## Why RAGBrain

Every fact is stored on two independent time axes: when it was true in the world (event
time) and when the system learned it (system time). The second axis is what makes answers
defensible rather than merely plausible.

Consider one fact that changed: Acme Corp's HQ was Boston (2019 filing), then Denver
(2022 filing).

| Question | Vector RAG | Valid-time RAG | RAGBrain |
|---|---|---|---|
| Where is Acme HQ now? | ✅ Denver | ✅ Denver | ✅ Denver |
| Where was it in 2020? | ❌ | ✅ Boston | ✅ Boston |
| What did we believe in 2021, before the 2022 filing? | ❌ | ❌ | ✅ **Boston, Denver un-known** |
| Show the timeline and what superseded what | ❌ | ⚠️ partial | ✅ full provenance and audit |

The third row is system-time replay. It requires an independent record of when each fact was
learned, and the discipline never to let a later correction leak into a past belief state:
the un-knowing invariant, enforced in CI against a live graph store.

## Capabilities

- **Bi-temporal knowledge graph.** Four timestamps per fact (`valid_at`, `invalid_at`,
  `created_at`, `expired_at`) in FalkorDB or Neo4j.
- **As-of retrieval.** Ask any question as of any instant; context is validity-filtered
  before ranking.
- **System-time replay and audit.** Reconstruct what the system believed at any past moment;
  a live web scrubber makes it visible.
- **Supersession with provenance.** A correcting fact expires the old one and stamps a
  `superseded_by` back-link at write time; every answer carries citations.
- **Checked generation.** Answers are verified claim-by-claim against the served facts after
  generation; unsupported claims are flagged, never silently shipped.
- **Pluggable everything.** Embedder, reranker, generation model, and graph backend are
  config-selected and fail loud; bring hosted APIs or fully local models.
- **Secure by default.** Bearer-token auth, token-scoped sessions, rate limits, upload caps.
- **Multi-replica ready.** Shared session state and a shared durable write-back journal,
  proven by a two-replica test; a metrics endpoint for operations.
- **Self-hostable end to end.** Your documents, your models, your infrastructure.

## What you can build with it

- **Agent memory that survives the session.** Give an LLM agent long-term memory over your
  documents and its own observations, with citations attached to every fact it recalls.
- **Compliance and audit copilots.** Answer "what did our policy say in March, and what did
  we believe at the time?" with a defensible provenance trail rather than a plausible guess.
- **Financial, legal, and medical retrieval** where a superseded fact is not merely stale but
  wrong, and where the correction history itself is part of the record.
- **Enterprise knowledge bases** that change constantly: pricing, org charts, contracts,
  specifications, SOPs. Corrections supersede instead of silently overwriting.
- **Hallucination and grounding checks.** Answers are constrained to retrieved context and
  verified claim by claim; unsupported claims are flagged, never quietly shipped.
- **RAG evaluation and regression testing** against a corpus whose truth changes over time.

## Where RAGBrain fits

The agent-memory and RAG ecosystem is crowded, and most of it is complementary rather than
competing. Roughly how the categories divide:

| Category | Examples | What they optimise for |
|---|---|---|
| Memory layers for agents | Mem0, Zep, Letta | extracting, consolidating and recalling user-level memory |
| RAG frameworks | LangChain, LlamaIndex, Haystack | orchestration, connectors, retrieval pipelines |
| Temporal knowledge graphs | Graphiti, cognee | storing facts with time attached |
| **RAGBrain** | this project | **auditable temporal correctness: as-of retrieval, system-time replay, and provenance you can defend** |

RAGBrain is built on a temporal graph substrate (Graphiti on FalkorDB or Neo4j) and focuses
on the layer above it: enforcing that a replay of the past cannot be contaminated by facts
learned later, and exposing that guarantee through an auditable API. It is designed to sit
underneath an agent framework, not to replace one.

Measured comparisons against LlamaIndex, LangChain, Haystack, and a temporal-graph ablation
are in [Benchmarks](#benchmarks), with a reproduce command. Systems not listed there have not
been benchmarked here, and no claim is made about them.

## Quick start

No Docker, no database, no API keys. Just:

```bash
pip install ragbrain
```

```python
from ragbrain import MemoryLedger

db = MemoryLedger()
db.remember("Acme HQ is Boston", key="acme.hq", valid_at="2019-01-01")
db.remember("Acme HQ is Denver", key="acme.hq", valid_at="2022-01-01")  # supersedes

db.answer("Where is Acme HQ?")                       # Acme HQ is Denver
db.answer("Where is Acme HQ?", as_of="2020-01-01")   # Acme HQ is Boston
db.replay("2021-06-01")[0].statement                 # Acme HQ is Boston
```

That third line is the one nothing else does. Replaying to June 2021 returns Boston
**with no end date**, because the 2022 correction had not been learned yet. The past is
reconstructed as it was believed, not as it was later revised.

`MemoryLedger` is a real bi-temporal ledger, not a demo prop: it passes the same substrate
conformance suite as the graph backends and shares their replay code. It runs in one process
with lexical matching and no persistence, so use FalkorDB or Neo4j (below) for semantic
retrieval, extraction, and durability.

<details>
<summary><b>The full platform, with a graph backend and the web UI</b></summary>
<br>

Prereqs: Docker. No API keys required for the demo.

```bash
git clone https://github.com/Nagendhra-Madishetti/ragbrain && cd ragbrain
docker compose up -d --build
bash scripts/demo.sh
```

The demo seeds the Acme scenario and asserts four answers:

```
now              -> Denver
as of 2020       -> Boston
replay(2021)     -> Boston   (the 2022 Denver correction is un-known)
timeline         -> Boston (2019 report) superseded by Denver (2022 press release)
```

</details>

Open the live scrubber at http://localhost:3000/playground and drag the system-time slider
across 2022; the answer flips in front of you:

[![System-time replay: scrubbing past the 2022 correction flips the belief Boston to Denver](docs/media/replay-demo.gif)](https://nagendhra-madishetti.github.io/ragbrain/replay.html)

**[Try it live: drag the system-time slider yourself](https://nagendhra-madishetti.github.io/ragbrain/replay.html)**

### Install as a library

```bash
pip install ragbrain          # import ragbrain
pip install "ragbrain[all,serve]"   # backends + the platform API
```

## Architecture

<img width="1060" alt="RAGBrain architecture" src="docs/media/architecture.png" />
The core is dependency-free: `ragbrain.core` imports only the standard library. Storage,
models, and retrieval are adapters behind stable interfaces, selected by configuration.

### The bi-temporal model

- Event time `[valid_at, invalid_at)`: when the fact was true in the world. Answers
  "as of 2020".
- System time `[created_at, expired_at)`: when the system learned or retracted it. Answers
  "what did we believe at S" and powers the un-knowing replay.
- A correction supersedes: the old fact receives `invalid_at` (event) and `expired_at`
  (system) plus a `superseded_by` back-link, stamped at write time.
- Replay to S drops everything learned after S, including the knowledge that a fact was
  later corrected. That is the invariant, enforced two ways: as pure deterministic tests and
  live against a FalkorDB service in CI (`tests/integration/test_replay_seeded.py`).

## Benchmarks

All published numbers come from live, reproducible runs on a fictional corpus (invented
companies, dates only in metadata), so no model can answer from training. Results carry a
content hash and a reproduce command; scores are claims exactly the size of the measurement.

| Comparison | Chart |
|---|---|
| As-of questions vs LlamaIndex, LangChain, Haystack, and a temporal-graph ablation | ![As-of benchmark](docs/media/benchmark-asof.png) |
| Current-fact questions (the honest tie) | ![Standard benchmark](docs/media/benchmark-standard.png) |

Reproduce: `python demo/benchmark_frameworks.py`. Full per-question answers, methodology,
and the measured evaluation floors (verify recall, faithfulness checker precision and recall)
are in the web app's Benchmark page and [PROJECT_STATUS.md](PROJECT_STATUS.md).

## API

Every route except `/api/health` requires a bearer token (`RAGBRAIN_API_TOKENS`; the compose
stack provisions `ragbrain-demo-token`). A session is scoped to the token that created it.

```bash
TOKEN=ragbrain-demo-token
API=http://localhost:8000
H="Authorization: Bearer $TOKEN"

curl -H "$H" -X POST "$API/api/demo/seed"
curl -H "$H" "$API/api/audit/current?session_id=demo_acme"
curl -H "$H" "$API/api/audit/event?session_id=demo_acme&as_of=2020-06-01"
curl -H "$H" "$API/api/audit/replay?session_id=demo_acme&system_time=2021-06-01"
curl -H "$H" "$API/api/audit/timeline/demo-belief-boston?session_id=demo_acme"

curl -H "$H" -H 'Content-Type: application/json' -X POST "$API/api/context" \
     -d '{"session_id":"mine","query":"Where is Acme headquartered?","as_of":"2020-06-01"}'
```

Ingest your own documents (local; data never leaves your environment):

```bash
cp .env.example .env    # provider keys for generation and semantic retrieval
curl -H "$H" -F session_id=mine -F reference_time=2019-01-01 \
     -F file=@your_report.pdf "$API/api/ingest"
```

For semantic retrieval configure a real embedder: `RAGBRAIN_EMBEDDER=bge-m3-local`
(key-free, requires the `[embeddings]` extra) or `RAGBRAIN_EMBEDDER=bge-m3` with
`RAGBRAIN_EMBEDDER_API_KEY`. The key-free boot default (`hash`) is lexical and states so
loudly in every response until a real embedder is configured.

## Deployment

- Local and trusted environments: `docker compose up -d --build`.
- Multi-replica: `docker compose -f docker-compose.yml -f docker-compose.replicas.yml up -d`
  with `RAGBRAIN_SHARED_STATE=1`; verify with `bash scripts/two_replica_proof.sh`.
- Operations: an authenticated `/metrics` endpoint exposes per-replica counters.
- Security posture, scope, and the operator checklist: [SECURITY.md](SECURITY.md).
  Project status and measured evaluation floors: [PROJECT_STATUS.md](PROJECT_STATUS.md).
  Defect ledger: [docs/KNOWN_ISSUES.md](docs/KNOWN_ISSUES.md).

## Documentation

| Topic | Where |
|---|---|
| Context-serving API | [docs/CONTEXT_API.md](docs/CONTEXT_API.md) |
| Audit and replay | [docs/AUDIT_DASHBOARD.md](docs/AUDIT_DASHBOARD.md) |
| Document ingestion | [docs/DOCUMENT_INGESTION.md](docs/DOCUMENT_INGESTION.md) |
| Embedders | [docs/EMBEDDERS.md](docs/EMBEDDERS.md) |
| Generation and faithfulness | [docs/GENERATION.md](docs/GENERATION.md) |
| Extending without touching core | [docs/EXTENDING.md](docs/EXTENDING.md), [CONTRIBUTING.md](CONTRIBUTING.md) |

## FAQ

**What is bi-temporal RAG?**
Retrieval-augmented generation where every fact carries two independent time axes: *event
time* (when it was true in the world) and *system time* (when the system learned it). That
second axis is what lets you ask "what did we believe last March?" and get an answer that
excludes everything learned since.

**How is this different from a vector database?**
A vector store answers "what is semantically similar". It has no notion of a fact being
superseded, so a corrected document and its replacement both remain retrievable with no
ordering between them. RAGBrain keeps the correction history and filters by validity before
ranking, so an as-of query cannot return a fact that was not yet true.

**Can I use it as memory for an LLM agent?**
Yes. That is the primary use case. Facts can be written by ingestion or by the agent itself
via `record_observation`, and served back through a context API, an MCP server, or the HTTP
API, each answer carrying citations and validity windows.

**Does it work with LangChain or LlamaIndex?**
Yes. RAGBrain is a memory and retrieval layer, not an agent framework. It ships a LlamaIndex
bridge, and the HTTP and MCP surfaces work with any orchestrator.

**Which LLM and embedding models does it support?**
Any OpenAI-compatible endpoint for generation, and local (`bge-m3`) or hosted embedders.
Every plug is config-selected and fails loud rather than silently degrading. There is a
key-free deterministic default so the demo runs with no API keys.

**Do I have to send my data to a third party?**
No. The whole stack is self-hostable: FalkorDB or Neo4j for storage, local embedding and
reranking models, and your own inference endpoint.

**Is it production ready?**
It is early. The core contracts, replay invariant, and multi-replica behaviour are covered by
164 tests in CI including a live graph database. Read
[PROJECT_STATUS.md](PROJECT_STATUS.md) for measured evaluation floors and
[docs/KNOWN_ISSUES.md](docs/KNOWN_ISSUES.md) for the open defect ledger before deploying.

**How does it prevent hallucinations?**
Generation is constrained to the served context, then every claim in the answer is checked
back against those facts. Unsupported claims are flagged or the answer is declined, depending
on the configured mode. It reduces unsupported output; it does not eliminate it.

## Development

```bash
pip install -e ".[dev]"
ruff check .
pytest
```

## License

Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
