ContextFlow

Open-source context infrastructure for AI agents.

Give your agents the right context at the right time — regardless of which LLM, agent framework, or data stack you use.

Quick Start · Docs · Architecture · Contributing

Why ContextFlow

Before — naive RAG

Agent → Vector DB → Top 5 chunks → LLM

With ContextFlow

Agent → Context Engine → Context Pack → LLM
              │
              ├── Semantic Search
              ├── Knowledge Graph
              ├── Memory
              ├── Permissions
              ├── Freshness
              ├── Conflict Detection
              └── Context Compiler

AI agents don't primarily need more tokens. They need the right context at the right time.

Related MCP server: ContextAtlas

Quick Start

git clone https://github.com/yourorg/contextflow
cd contextflow
pip install -e .
contextflow demo

That's the whole thing — contextflow demo writes sample docs, ingests them, runs a search, and builds a Context Pack, so you see the full flow work with zero configuration before touching your own data. This has been verified end-to-end from a clean clone into a fresh virtualenv with no pre-existing dependencies — see docs/getting_started.md for the exact commands.

For your own data:

contextflow init
contextflow ingest ./your-docs
contextflow search "your query"
contextflow context-pack "your question"

ingest, search, and context-pack are separate commands that persist to .contextflow/ on disk — no long-running process required.

For Postgres/Qdrant/Neo4j instead of the local-first defaults:

cp .env.example .env
docker compose up

from contextflow import ContextEngine

engine = ContextEngine()

context = engine.retrieve(
    query="Why did our revenue drop last quarter?"
)

print(context)

Note on retrieval quality: with no configuration, semantic search uses a dependency-free hashing placeholder with no real language understanding — fine for the quickstart above, not for real retrieval quality. Set CONTEXTOS_EMBEDDING_PROVIDER=openai (or ollama / cohere) plus the matching API key before ingesting real data:

export CONTEXTOS_EMBEDDING_PROVIDER=openai
export OPENAI_API_KEY=sk-...
contextflow ingest ./docs

See src/contextflow/embeddings/ — Ollama runs fully locally if you'd rather not use a hosted API.

Other local-first commands

contextflow trace "your query"    # see exactly what the retrieval pipeline did
contextflow mcp                   # expose an MCP server to Claude, Cursor, etc.

context-pack prints a readable panel:

╭──────────────────────────── Context Pack ────────────────────────────╮
│ Query: What decisions were made about payments?                      │
│                                                                        │
│ Documents                                                             │
│   • Stripe was selected as the payment processor. The migration…     │
│                                                                        │
│ Sources                                                                │
│   • filesystem                                                        │
│                                                                        │
│ Confidence: 100%                                                      │
╰────────────────────────────────────────────────────────────────────────╯

Swap in Postgres, Qdrant, and Neo4j later when you need to scale — see docs/deployment.

The core abstraction: Context Pack

Instead of raw chunks:

context = engine.context_pack(
    task="prepare customer renewal",
    entity="Acme",
)

{
  "entity": "Acme",
  "facts": [],
  "people": [],
  "projects": [],
  "conversations": [],
  "documents": [],
  "decisions": [],
  "risks": [],
  "relationships": [],
  "sources": [],
  "conflicts": [],
  "confidence": 0.94
}

MCP native

ContextFlow ships an MCP server out of the box, so any MCP-compatible agent (Claude, Cursor, custom agents, ...) can call:

search_context()
get_entity()
get_context_pack()
get_relationships()
get_memory()
get_source()
explain_context()

contextflow mcp

Modular by design

Don't want the knowledge graph? Don't install it. Every subsystem is an interface with swappable backends:

See ARCHITECTURE.md for the full picture and ROADMAP.md for what's built vs. planned in v0.1.

Repository layout

src/contextflow/
├── core/          # Context Object, Context Pack, Entity, Relationship
├── ingestion/      # Parsing, chunking, normalization, dedup
├── retrieval/      # Semantic, keyword, graph, hybrid, reranking
├── graph/          # Graph building, entity resolution, traversal
├── memory/         # Working / session / user / agent / org memory
├── compiler/       # Context compilation, compression, conflict detection
├── governance/      # Permissions, policies, PII detection, audit
├── evaluation/      # Retrieval + faithfulness benchmarks
├── connectors/      # GitHub, PostgreSQL, filesystem (+ Connector SDK)
├── mcp/             # MCP server and tools
├── api/             # REST API
└── cli/             # `contextflow` command-line tool

Status

ContextFlow is v0.1 — early, opinionated, and built for contribution. What's real today: persistent local storage, hybrid retrieval, real embedding providers (OpenAI/Cohere/Ollama), API key auth shared by the REST API and MCP-over-HTTP, RBAC + tenant isolation + pattern-based PII detection + queryable audit logging, five-tier memory (session/user/agent/org persisted, working ephemeral by design), real pipeline tracing/ observability (contextflow trace), a real TypeScript SDK (sdk/typescript) tested against a live server, ContextBench v0.1 (a real, non-trivial retrieval benchmark with Recall/Precision/MRR/NDCG and an honestly documented synthetic-data methodology), real measured performance/scale benchmarks that found and fixed a genuine O(n²) ingestion bug (contextflow benchmark-scale), GitHub/PostgreSQL/filesystem connectors proven end-to-end against real infrastructure, Slack and Notion connectors proven against mocked APIs but not yet live workspaces, a naive-but-functional knowledge graph, a runnable evaluation harness, and the CLI/REST/MCP surfaces above.

The honest gap: benchmarked against LoCoMo (a real external benchmark also used by Mem0/Zep/Letta — see benchmarks/external/locomo/), the zero-config default scored 8.5% Recall@5. The best configuration tested in this environment — SpacyEmbeddingProvider with en_core_web_lg, fully local, zero API keys — reached 27.3%, a real ~3.2x improvement. This does not beat the benchmark: a comparable published system reports 93.9% on the same dataset. The remaining gap has two specific, identified causes (no trained sentence encoder or LLM-based fact extraction was accessible in this sandbox), not a mystery — see benchmarks/external/locomo/RESULTS.md for the full honest accounting.

See ROADMAP.md for the full phased plan — including what's shipped, what's partially built, and what's still just direction — and CONTRIBUTING.md for how to help.

License

Apache 2.0 — see LICENSE.