Context infrastructure for the agentic era.
Every AI agent session starts from zero. Every handoff between agents loses context. Every team member spends days absorbing tribal knowledge that no tool captures.
Contextually solves the three context problems nobody has solved:
- Context continuity — Cursors persist what was explored, what was useful, and where to resume. Your second session is faster than your first.
- Context transfer — Handoff packages carry everything the next actor needs: key files, observations, navigation history. Zero-loss agent-to-agent and agent-to-human transfer.
- Context assembly — An 8-stage pipeline answers "given 50K tokens and this task, what is the optimal set of files at what level of detail?" using graph centrality, proximity, churn, and learned weights.
The engine is domain-general. Today it indexes codebases. The same graph, assembly pipeline, and learning loop work for any knowledge domain — legal, medical, data, research — without core changes.
# Quick install (Linux/macOS)
curl -fsSL https://get.syncropic.com/cxl | sh
# From source
cargo install --git https://github.com/syncropic/contextually.gitPre-built binaries: Linux (x86_64, aarch64), macOS (x86_64, aarch64), Windows (x86_64) on Releases.
# 1. Initialize — index your project into a graph
cxl init
# Creates a starter cursor with your top central files automatically
# 2. Resume — start warm, every session
cxl resume # loads most recent cursor, refreshes, assembles
cxl resume --task CMT-0042 --lens agent # by task
# 3. Gather — discover context across projects
cxl gather "auth" -s ~/repositories --save my-cursor
cxl gather "streaming" -s ~/drafts --save my-cursor # merges into same cursor
# 4. Refine — curate the context packet
cxl cursor amend my-cursor --boost src/auth.rs --relevance 0.95 --tier T3
cxl cursor amend my-cursor --remove old/noise.rs
cxl cursor amend my-cursor --note "key design doc for auth redesign"
# 5. Observe — record what was useful during work
cxl observe useful src/auth.rs -c my-cursor
cxl observe noise src/legacy/old.rs -c my-cursor
# 6. Handoff — transfer to the next actor
cxl handoff my-cursor next-agent -m "auth fix ready for review"Observations feed back into assembly ranking automatically. The system gets smarter with every session.
cxl init builds a graph of your project:
- Nodes: files, directories, reference nodes (external resources like tickets, URLs, schemas)
- Edges: parent/child, co-change (from git history), manual links, ticket references
- Scores: PageRank centrality, change frequency, content hashes
- Summaries: T1 structural extraction for 13 languages (Rust, Python, JS/TS, Go, Java, C/C++, SQL, Shell, YAML, TOML, JSON, Markdown)
The assembly pipeline then ranks and budgets context:
Seed nodes → Graph expansion → Rank by (centrality x proximity x churn x learned_boost)
→ Budget across tiers (T0: name, T1: signatures, T3: full content)
→ Format for the requesting actor
# During work, record what helped and what didn't
cxl observe useful src/auth.rs -c cursor-123
cxl observe noise src/legacy/old_auth.rs -c cursor-123
cxl observe missing "webhook handler for auth events" -c cursor-123
# Future assemblies automatically boost useful files, suppress noise
# No manual step — learned_boost feeds directly into the ranking formula
# Publish learnings across projects
cxl learn --publishWorks with CatchMyTask for automatic context lifecycle. cmt manages work (what, why, status). cxl manages context (what files, what detail, how fresh). They share a task ID and nothing else.
# One command: looks up the task, extracts file references,
# creates/resumes a persistent cursor, assembles context
cxl assemble --task CMT-0042 --lens agent
# Install hooks for automatic cursor creation on task start
cxl hooks install-cmtcxl reads from cmt (via cmt show --json) but never writes to it. cmt triggers cxl via hooks but never modifies .contextually/. See Design: cmt Integration Protocol.
For the full orchestration picture (cmt + cxl + dpagent), see Design: Three-Tool Stack.
Ticket IDs in git commits (e.g., PROJ-123) are automatically detected and linked as reference nodes during indexing.
cxl impact src/auth.rs # what breaks if this changes?
cxl depends src/main.rs # what does this need?
cxl why src/auth.rs src/db.rs # explain the relationship
cxl rank --by centrality # most important files
cxl rank --by churn # most frequently changed
cxl cluster --around src/auth.rs # tightly connected groupExtend the graph beyond the filesystem:
cxl link-ref "https://jira.example.com/PROJ-123" --title "Auth bug" --source jira
cxl link "ref:jira-PROJ-123" src/auth.rs implements
# Reference nodes appear in assembly, impact analysis, and all graph queries| Lens | Format | Use Case |
|---|---|---|
agent |
XML tags (<system_context>, <context_window>) |
AI agent consumption |
terminal |
Colored markdown | Human reading |
roundtrip |
## /path + code fences |
Editable (use with cxl apply) |
compact |
Minimal tokens | Budget-constrained |
Pre-built recipes that auto-match based on task description:
cxl assemble --pattern bug-investigation src/auth.rsBuilt-in: bug-investigation, feature-development, code-review. Patterns resolve hierarchically: cursor -> project -> global catalog -> built-in.
.contextually/ ~/.config/cxl/
index.db (SQLite graph) catalog.db (cross-project intelligence)
cursors/ (session state)
observations/ (learning signals)
patterns/ (assembly recipes)
- Local owns truth. Each project's
.contextually/is the source of truth. - Global aggregates. The catalog learns across projects but never overrides.
- External stays external. Reference nodes address resources without copying data.
- SQLite everywhere. WAL mode, busy_timeout, no servers, no accounts.
See AGENT.md for the structured entry point. Set CXL_ACTOR and use --json on every command.
- AGENT.md — universal agent entry point
- Online Docs — comprehensive reference
- Design: Why cxl Exists — first-principles analysis
- Design: Agentic Context Gathering — LLM-orchestrated assembly architecture
- Design: cmt Integration Protocol — how cxl and cmt complement each other
- Design: Three-Tool Stack — cmt + cxl + dpagent roles and boundaries
MIT