reasongraph

# ReasonGraph

A graph-based **memory for AI agents**: it ingests facts, auto-extracts entities and cause->effect relations, and discovers connections across independent documents *and* across agent sessions -- with conflict resolution, time-travel, causal tracing, and counterfactuals.

[![PyPI version](https://img.shields.io/pypi/v/reasongraph?color=blue)](https://pypi.org/project/reasongraph/)
[![Python 3.11+](https://img.shields.io/pypi/pyversions/reasongraph?color=blue)](https://pypi.org/project/reasongraph/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Why ReasonGraph?

Standard RAG retrieves documents similar to your query. ReasonGraph is a persistent, updatable memory that discovers connections *between* facts that were written independently.

When you feed text into `add_texts()`, ReasonGraph automatically extracts **entities** (via GLiNER) and **cause-effect relations** (via a dedicated causal model) that become nodes and typed edges in a graph. Facts that share entities or causal chains get connected -- even if they never reference each other. Multi-hop traversal then walks these connections to build reasoning chains that span multiple sources.

On top of retrieval it works as agent memory: **scopes/sessions** (agents discover into each other's memory through shared entities), **contradiction resolution** (a new fact soft-supersedes what it contradicts), **time-travel** (`query(as_of=...)`), **causal tracing** (`trace_effects` / `root_causes` / `causal_chain`), **counterfactuals** (`what_if`), and a shippable **MemoryService** over HTTP and MCP.

**Zero config, strong defaults.** `ReasonGraph()` picks the best available entity extractor, causal model, embedder, and reranker automatically -- the eval numbers below come from these defaults. For the SOTA causal model (~0.70 F1) use `pip install reasongraph[causal]` and the graph uses it automatically. The configuration sections are optional depth, not required reading.

## Use it in 60 seconds

**Claude Code / Cursor / any MCP client, hosted (EU, no LLM in the loop):**

```bash
claude mcp add --transport http memory https://memory.primaxiom.ai/mcp \
  --header "Authorization: Bearer rgm_YOUR_KEY"
```

**Python, in-process:**

```bash
pip install "reasongraph[all]"
```

```python
from reasongraph import ReasonGraph

graph = ReasonGraph()
graph.initialize_sync()
graph.add_texts_sync(["TSMC is building a chip fab in Phoenix, Arizona.",
                      "Arizona ordered water cuts for industrial users in Maricopa County."])
print(graph.discover_sync("water and chips"))   # a path: water cuts -> Arizona -> TSMC fab
```

**Any language, over HTTP (self-hosted or hosted):**

```bash
curl -X POST https://memory.primaxiom.ai/sessions/notes/memory \
  -H "Authorization: Bearer rgm_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"text": "Apple sources M-series chips from TSMC in Arizona."}'
```

Ready-to-copy agents (Groq/OpenAI-compatible research agent, two agents sharing one
memory, Claude Code with persistent memory, LangGraph) live in
[`examples/agents/`](examples/agents/).

### Hosted: ReasonGraph Cloud

[memory.primaxiom.ai](https://memory.primaxiom.ai) runs this library as a service: sign in,
get a free key (10k requests a month), remote MCP endpoint, browser console and playground.
Extraction runs with small models on servers PrimAxiom operates (currently in the EU); facts are
only sent to an LLM provider if you ask for a synthesized answer. Early access.

## Installation

```bash
pip install reasongraph[all]        # everything included
```

Or install only what you need:

```bash
pip install reasongraph             # core: in-memory backend, NER extraction, embeddings
pip install reasongraph[gliner]     # + GLiNER entity extraction + hybrid causal (default, recommended)
pip install reasongraph[causal]     # + SOTA span-pointer causal model (~0.70 F1) + hybrid fallback
pip install reasongraph[gliner2]    # + GLiNER2 alternative (single model does entities + causal)
pip install reasongraph[sqlite]     # + SQLite backend with sqlite-vec
pip install reasongraph[postgres]   # + PostgreSQL + pgvector backend
pip install reasongraph[service]    # + HTTP + MCP memory service
pip install reasongraph[fastembed]  # + pure-ONNX embedder / reranker (faster cold start)
```

## Cross-Source Discovery

Two reports about different topics. Source A covers TSMC's semiconductor plant. Source B covers Arizona's water crisis. Neither mentions the other's subject.

```python
import asyncio
from reasongraph import ReasonGraph

source_a = [  # Tech industry report
    "TSMC announced plans to build a $40 billion semiconductor fabrication plant in Phoenix, Arizona.",
    "The Phoenix fab requires 10 million gallons of purified water daily to cool wafers during the chip etching process.",
    "TSMC signed a long-term supply agreement with Apple to manufacture next-generation M-series processors at the Arizona facility.",
    "Construction delays at the Phoenix site pushed first production to late 2025, raising concerns among TSMC's major customers.",
]

source_b = [  # Environmental report -- never mentions TSMC, semiconductors, or chips
    "Arizona declared a water emergency after Lake Mead dropped to its lowest level since the 1930s, threatening water supply for millions.",
    "The Arizona Department of Water Resources ordered mandatory water cuts for all industrial users in Maricopa County, where Phoenix is located.",
    "Intel paused expansion of its Chandler, Arizona chip plant citing water availability concerns and rising operational costs.",
    "Apple warned investors that component shortages from its Asian and North American suppliers could impact iPhone production timelines through 2026.",
]

async def main():
    async with ReasonGraph() as graph:
        await graph.add_texts(source_a)
        await graph.add_texts(source_b)
        results = await graph.query("How does the Arizona water crisis affect semiconductor manufacturing?")
        for i, text in enumerate(results, 1):
            source = "A" if text in source_a else "B"
            print(f"{i}. [Source {source}] {text}")

asyncio.run(main())
```

```
1. [Source B] Intel paused expansion of its Chandler, Arizona chip plant citing water availability concerns and rising operational costs.
2. [Source B] The Arizona Department of Water Resources ordered mandatory water cuts for all industrial users in Maricopa County, where Phoenix is located.
3. [Source A] The Phoenix fab requires 10 million gallons of purified water daily to cool wafers during the chip etching process.
4. [Source B] Arizona declared a water emergency after Lake Mead dropped to its lowest level since the 1930s.
5. [Source A] TSMC announced plans to build a $40 billion semiconductor fabrication plant in Phoenix, Arizona.
6. [Source A] TSMC signed a long-term supply agreement with Apple to manufacture M-series processors at the Arizona facility.
```

Results come from both sources. No single document contains this chain. Here is what happens under the hood:

**ReasonGraph extracts entities and causal relations from each text** (requires an entity+causal extractor, e.g. `pip install reasongraph[gliner]` or `[all]`)**:**

| Text (abbreviated) | Entities | Causal relations |
|---------------------|----------|------------------|
| TSMC to build fab in Phoenix, Arizona... | TSMC, Phoenix, Arizona | -- |
| Phoenix fab requires 10M gallons water... | Phoenix | -- |
| TSMC supply agreement with Apple... | TSMC, Apple, Arizona | -- |
| Construction delays at Phoenix site... | TSMC, Phoenix | Construction delays -> first production |
| Arizona water emergency, Lake Mead... | Arizona, Lake Mead | Lake Mead dropped -> water emergency |
| Mandatory water cuts in Maricopa County... | Arizona Dept. of Water Resources, Phoenix, Maricopa County | -- |
| Intel paused Arizona chip plant... | Intel, Chandler, Arizona | -- |
| Apple warned of component shortages... | Apple | component shortages -> iPhone production timelines |

**Three entities appear in both sources, creating bridge nodes:**

| Bridge entity | Source A connections | Source B connections |
|---------------|---------------------|---------------------|
| Arizona | TSMC fab, TSMC-Apple deal | water emergency, Intel pause, water cuts |
| Phoenix | TSMC fab, water usage, delays | water cuts for industrial users |
| Apple | TSMC supply agreement | component shortage warning |

**The query traversal path:**

Water crisis query -> finds water-related texts from both sources via embeddings -> follows `Arizona` and `Phoenix` entity edges to discover TSMC's water-intensive fab -> follows `Apple` entity edge from TSMC supply agreement to Apple's component shortage warning. The causal relation `Lake Mead dropped -> water emergency` connects the environmental trigger to the industrial impact.

Full demo: `uv run python examples/cross_source_discovery.py`

## Quick Start

### Using a built-in dataset

```python
from reasongraph import ReasonGraph

graph = ReasonGraph()
graph.initialize_sync()
graph.load_dataset_sync("financial")

results = graph.query_sync("What caused the 2008 financial crisis?")
for i, text in enumerate(results, 1):
    print(f"{i}. {text}")

graph.close_sync()
```

Output -- a connected reasoning chain, not just keyword matches:

```
1. Lehman Brothers filed for bankruptcy in September 2008 after massive MBS losses.
2. Loose lending standards fueled a housing price bubble across the United States.
3. Lehman's collapse triggered a global credit freeze as interbank lending stopped.
4. Mortgage-backed securities built on subprime loans collapsed when defaults surged.
5. The U.S. government enacted TARP, a $700 billion bailout to stabilize the financial system.
6. Banks issued subprime mortgages to borrowers with poor credit histories.
```

### Async API

```python
import asyncio
from reasongraph import ReasonGraph

async def main():
    async with