A shared context layer for humans and AI agents.
Substrate provides persistent, graph-backed context that syncs across contributors and devices through git — context lives in committed .substrate/ files, with no server and no accounts.
- Agents lose context between sessions. Substrate gives them deterministic retrieval.
- Teams lose context across repos and contributors. Substrate provides shared truth, versioned alongside the code.
- Static docs rot. Substrate context is structured and dynamic.
- No server to run. Sync rides on the git infrastructure you already have; identity and access control are your git host's.
npm install -g substrate-cliOr from source:
git clone <repo-url> substrate
cd substrate/cli
npm install && npm link# Initialize the context store (no account needed)
substrate init myproject
# Add context
substrate add "All API responses must be JSON" --type constraint
substrate add "Using PostgreSQL for persistence" --type decision
substrate add "My local DB runs on port 5544" --type note --private # personal, not committed
# Share it: write the .substrate files, then commit with git
substrate sync push
git add .substrate && git commit -m "Add context" && git push
# Get context brief (for agents)
substrate brief --format agent
substrate brief --budget medium # Token-aware output| Concept | Description |
|---|---|
| Store | A repo's .substrate/ directory — the context store, found by walking up like .git |
| Context | Typed objects: constraints, decisions, notes, tasks, entities |
| Links | Graph relationships between context objects |
| Brief | Agent-optimized context retrieval |
One repo = one .substrate/ = one context store. The repository is the identity; there's nothing to mount or pin.
| Type | Priority | Use For |
|---|---|---|
constraint |
Highest | Hard rules, immutable facts |
decision |
High | Architectural choices with rationale |
note |
Medium | General knowledge |
task |
Low | Work items |
entity |
Low | Domain concepts |
runbook |
Low | Operational procedures |
snippet |
Low | Canonical code patterns |
# Working on a feature...
substrate add "Auth tokens expire after 24h" --type constraint --tag auth
substrate add "Using JWT for stateless auth" --type decision --tag auth
# Link related concepts
substrate ls # Get IDs
substrate link add abc123 def456 --relation implements
# Later, or on another machine...
git pull && substrate sync pull # Reconcile committed context into the local cache
substrate brief --format agent # Rehydrate context
# Share with teammates
substrate sync push # Write the .substrate files
git add .substrate && git commit -m "..." && git push- Getting Started — Installation and first steps
- CLI Reference — Complete command documentation
- Sync & Sharing — Git-backed sync and the shared/private stores
- GitHub Action — Surface governing context on every PR
- Claude Code plugin — installable plugin: asks once per project to track context, captures decisions/constraints, and registers the MCP server
- Codex & other agents — portable
AGENTS.mdprotocol + MCP config for Codex, Cursor, Windsurf, etc. - Claude Code — CLAUDE.md integration
- Cursor — .cursor/rules integration
- Windsurf — .windsurf/rules integration
- GitHub Copilot — copilot-instructions.md integration
- Zed — .rules file integration
- Warp — AI terminal integration
- MCP Server — Native tool integration
MIT