Universal Context

Your AI agents forget everything. Universal Context fixes that.

Operational memory for AI coding agents. Captures every session, distills working memory,
and gives your agents searchable context across your entire coding history.

             ┌─────────────────────────────────────────┐
             │            UC Daemon                     │
             │                                         │
             │   Watcher              Worker           │
             │   ┌──────────────┐    ┌──────────────┐  │
             │   │ Claude Code  │    │ Summarizer   │  │
             │   │ Codex CLI    ├───►│ Embeddings   │  │
             │   │ Gemini CLI   │    │ Memory       │  │
             │   └──────┬───────┘    └──────┬───────┘  │
             │          └──────┬────────────┘          │
             │                 ▼                        │
             │          ┌────────────┐                  │
             │          │ SurrealDB  │                  │
             │          │ Graph DB   │                  │
             │          └────────────┘                  │
             └─────────────────────────────────────────┘

The Problem

AI coding agents are stateless. Every session starts from zero. That architectural decision you made last week, the bug you spent an hour debugging, the pattern you established across your codebase — all gone. Your agents keep re-discovering the same things, making the same mistakes, asking the same questions.

The Solution

Universal Context runs a background daemon that watches your AI coding sessions, captures every turn into a SurrealDB graph database with full provenance, summarizes them via LLM, generates local embeddings, and distills working memory per project. Your agents get searchable, scoped context — keyword, semantic, or hybrid — plus LLM-powered Q&A and agentic multi-hop reasoning across your entire history.

Local-first. Your data stays on your machine. No cloud, no telemetry, no third-party storage.

Supported Tools

Claude Code
_{Full JSONL conversation turns
Tool calls, file edits, reasoning}

Codex CLI
_{Event-stream responses
Code generation, shell commands}

Gemini CLI
_{JSON array conversations
Multi-turn context}

More adapters welcome — send a PR.

Features

Search & Retrieval

BM25 full-text search — keyword search with relevance ranking
Semantic vector search — local embeddings, no API keys needed
Hybrid search — RRF fusion of keyword + semantic
Scope filtering — search within a project or across everything
Branch filtering — scope queries to a specific git branch

Working Memory

Auto-distilled — LLM summarizes accumulated project knowledge
Injectable — pipe memory into CLAUDE.md, AGENTS.md, etc.
Refreshable — regenerate on demand as your project evolves

Context & Q&A

Natural language Q&A — "How does the auth middleware work?"
Agentic reasoning — DSPy RLM multi-hop exploration of your session history
Context retrieval — relevant sessions for a task description
JSON output — every command supports --json

Git-Aware Intelligence

Scope identity — worktrees and clones share one knowledge scope
Branch tracking — every run records its branch + commit SHA
Merge detection — detects when feature branches land on main
Cross-machine sharing — export/import bundles with scope metadata

Data Integrity

Graph provenance — full RELATE edge chain from scope to summary
Secret redaction — API keys, tokens, passwords stripped on capture
Immutable artifacts — summaries are derived, never mutated

Local-First by Default

Zero API keys required — embedded DB + local ONNX embeddings
Optional LLM — add an API key for better summaries and Q&A
Optional DB server — upgrade to BM25 + HNSW when ready
TUI dashboard — interactive overview, timeline, and search

Setup — Give This to Your Agent

The recommended way to set up UC is to paste this README into Claude Code, Codex, or any AI coding agent and tell it: "Install Universal Context for me."

Your agent can handle the entire setup autonomously.

If you prefer doing it yourself:

Prerequisites

Python 3.13+ — brew install python@3.13 or python.org
uv — curl -LsSf https://astral.sh/uv/install.sh | sh (docs)

Install

git clone https://github.com/mysticaltech/universal-context.git
cd universal-context
uv tool install --editable . --with anthropic
uc init

This puts uc on your PATH and creates ~/.uc/config.yaml.

Start the Daemon

uc daemon start -f

That's it. UC is now watching your AI coding sessions and building your operational memory.

SurrealDB Setup

Important: UC requires SurrealDB v3 (beta). The default installer gets v2 — you must pass --version to get v3. UC will not work with SurrealDB v2.

UC works in two modes:

Mode	Search Capabilities	Setup
Embedded (`file://`)	Substring match + brute-force cosine	Zero config — works out of the box
Server (`ws://`)	BM25 full-text + HNSW vector KNN	2 minutes — full-power search

The embedded mode works immediately with no extra setup. When you're ready for full-power search:

# Install SurrealDB v3 (must specify version — default installs v2)
curl -sSf https://install.surrealdb.com | sh -s -- --version v3.0.0-beta.4

# Verify you have v3
surreal version
# Expected: 3.0.0-beta.4

# Start the server
surreal start --bind 127.0.0.1:8000 --user root --pass root surrealkv://~/.surrealdb/data

Then point UC at it in ~/.uc/config.yaml:

db_url: "ws://127.0.0.1:8000"
db_user: "root"
db_pass: "root"

What you get: BM25 full-text search with relevance ranking, HNSW approximate nearest neighbor search for semantic queries, and automatic index rebuilds. Without it, search still works via substring matching and brute-force cosine similarity — just slower at scale.

Configuration

~/.uc/config.yaml:

# LLM for summarization and Q&A
# Works without any API key (extractive fallback), but much better with one
llm_provider: "openrouter"     # openrouter | claude | openai | auto
llm_model: ""                  # empty = provider default

# Embeddings — local by default, no API key needed
embed_provider: "local"        # local | openai

# API keys (or set via environment variables)
openrouter_api_key: ""         # or OPENROUTER_API_KEY env var
# anthropic_api_key: ""        # or ANTHROPIC_API_KEY env var
# openai_api_key: ""           # or OPENAI_API_KEY env var

# SurrealDB — optional server for full-power search
db_url: "ws://127.0.0.1:8000"
db_user: "root"
db_pass: "root"

# Which AI CLIs to watch
auto_detect_claude: true
auto_detect_codex: true
auto_detect_gemini: true

LLM Providers

Provider	Env Var	Notes
`openrouter`	`OPENROUTER_API_KEY`	Recommended. Multi-model gateway — one key, any model
`claude`	`ANTHROPIC_API_KEY`	Direct Anthropic API
`openai`	`OPENAI_API_KEY`	Direct OpenAI API
`auto`	Any of the above	Tries providers in priority order

Recommended model: Set llm_model: "x-ai/grok-4.1-fast" via OpenRouter. Fast, cheap, excellent at summarization. The default (Claude Haiku 4.5) works great too.

Embedding Providers

Provider	Model	Dims	API Key Required
`local`	EmbeddingGemma-300M (ONNX)	768	No
`openai`	text-embedding-3-small	1536	Yes

The local model downloads ~600MB on first use and caches at ~/.cache/uc-models/. No API keys, no PyTorch — pure ONNX inference.

CLI Reference

Public Commands (Default UX)

uc "what changed in scope identity?"       # Intent-first: routes to `uc ask`
uc ask "question" --project .              # Shallow Q&A
uc ask "question" --project . --deep       # Agentic deep reasoning (DSPy RLM)
uc remember "fact" --project . --type durable_fact
uc find "query" --project .                # Unified retrieval (auto mode)
uc find "query" --mode keyword             # BM25/substring retrieval
uc find "query" --mode semantic            # Vector retrieval
uc find "query" --mode hybrid              # Hybrid retrieval
uc status                                  # System overview
uc doctor                                  # Health check

Working Memory

uc memory show --project .                 # View distilled project memory
uc memory refresh --project .              # Regenerate from latest sessions
uc memory sync --project .                 # Refresh + inject (single command)
uc memory migrate-db --project .           # One-time DB -> durable file migration
uc memory remember "note" --project . --type procedure
uc memory inject --project .               # Write into AGENTS.md
uc memory inject -t CLAUDE.md              # Write into CLAUDE.md
uc memory eject --project .                # Remove injected memory
uc memory history --project .              # View memory versions

Daemon

uc daemon start                            # Start in background
uc daemon start -f                         # Start in foreground (see logs)
uc daemon stop                             # Stop the daemon

Admin Commands (Operator UX)

uc admin --help                             # Full operator surface
uc admin context --project . --branch main  # Run/branch context views
uc admin reason "question" -v               # Legacy deep-reasoning command
uc admin timeline --branch main             # Inspect run timelines
uc admin inspect turn:abc123                # Inspect provenance for a turn
uc admin share export run:abc123 -o bundle.json
uc admin share import bundle.json --project .
uc admin scope list --json
uc admin rebuild-index
uc admin db rebuild --json
uc admin db prove --project . --json
uc admin dashboard

Every command supports --json for machine-readable output. Alpha reset note: command surface is intentionally breaking while UX is being simplified.

Evaluation

# PR gate (deterministic smoke eval)
python3 eval/run_uc_smoke.py --json-out eval/uc_smoke_latest.json

# Scheduled calibration (LongMemEval)
python3 eval/run_longmemeval.py \
  --provider openrouter \
  --model x-ai/grok-4.1-fast \
  --max-questions 10 \
  --allow-skip \
  --install-requirements \
  --json-out eval/longmemeval_latest.json

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                          UC Daemon                              │
│                                                                 │
│  ┌─────────────────────────┐    ┌───────────────────────────┐   │
│  │        Watcher          │    │         Worker            │   │
│  │                         │    │                           │   │
│  │  Adapters               │    │  TurnSummarizer           │   │
│  │   Claude (.jsonl)       │    │   LLM summarize           │   │
│  │   Codex  (events)       │    │   Embed (ONNX/API)        │   │
│  │   Gemini (.json)        │    │   Scope propagation       │   │
│  │         │               │    │                           │   │
│  │  Triggers               │    │  MemoryProcessor          │   │
│  │   Turn detection ───────┼────┼─► LLM distillation        │   │
│  │   Turn ingestion        │jobs│   Project memory          │   │
│  │                         │    │                           │   │
│  │  Git awareness          │    │  HNSW Rebuilder           │   │
│  │   Branch, commit SHA    │    │   Auto every 25 embeds    │   │
│  │   Canonical ID, merges  │    │                           │   │
│  └─────────────────────────┘    └───────────────────────────┘   │
│                                                                 │
│                       ┌─────────────┐                           │
│                       │  SurrealDB  │                           │
│                       │  Graph DB   │                           │
│                       └─────────────┘                           │
└─────────────────────────────────────────────────────────────────┘

Provenance: scope ← run ← turn ← transcript ← summary  (all RELATE edges)
Search:     BM25 full-text │ HNSW vector KNN │ brute-force cosine fallback

Key Design Decisions

Decision	Rationale
Single-process daemon	RocksDB fcntl lock; watcher + worker as async task groups
Graph provenance	`RELATE` edges link every artifact to its source, fully traversable
Immutable summaries	Derived artifacts linked via `depends_on` edges, never mutated
Git-aware scopes	canonical_id from git remote URL — worktrees and clones share knowledge
Self-healing search	HNSW KNN with automatic brute-force cosine fallback
Denormalized scope	Scope field on artifacts avoids graph traversal on search hot path

For the full architecture guide, see AGENTS.md.

Contributing

PRs, not issues. We don't use GitHub Issues for bug reports. If you found a bug, fix it and send a PR. If you want to add a feature, send a PR.

Every PR must pass triple verification:

Check	Command
Tests pass	`pytest -x -v` (341+ tests)
Lint clean	`ruff check . && ruff format --check .`
Manual test	Verify your change works end-to-end

See CONTRIBUTING.md for the full guide.

Support the Project

If Universal Context saves you time, consider sponsoring to keep it maintained and evolving.

Apache 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.github		.github
eval		eval
skills/pulling-context		skills/pulling-context
tests		tests
universal_context		universal_context
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Universal Context

The Problem

The Solution

Supported Tools

Features

Search & Retrieval

Working Memory

Context & Q&A

Git-Aware Intelligence

Data Integrity

Local-First by Default

Setup — Give This to Your Agent

Prerequisites

Install

Start the Daemon

SurrealDB Setup

Configuration

LLM Providers

Embedding Providers

CLI Reference

Evaluation

Architecture

Key Design Decisions

Contributing

Support the Project

About

Uh oh!

Releases

Sponsor this project

Uh oh!

Packages

Languages

Uh oh!

License

mysticaltech/universal-context

Folders and files

Latest commit

History

Repository files navigation

Universal Context

The Problem

The Solution

Supported Tools

Features

Search & Retrieval

Working Memory

Context & Q&A

Git-Aware Intelligence

Data Integrity

Local-First by Default

Setup — Give This to Your Agent

Prerequisites

Install

Start the Daemon

SurrealDB Setup

Configuration

LLM Providers

Embedding Providers

CLI Reference

Evaluation

Architecture

Key Design Decisions

Contributing

Support the Project

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Languages

Packages