context-matters

Structured context store for AI agents. SQLite-backed, scoped, searchable.

Agents accumulate knowledge during sessions: decisions made, feedback received, patterns discovered, lessons learned. Without persistence, every session starts from zero. context-matters gives agents a place to store and retrieve that knowledge across sessions, projects, and scopes.

Install

npx context-matters serve    # MCP server on stdio

Or build from source:

cargo install --path crates/cm-cli

MCP server

Runs as a Model Context Protocol server. Ten tools, all prefixed cx_*.

cm serve

This CLI mirrors the MCP tool surface. From a shell, use cm <command>. From an MCP client, the same operations are exposed as cx_<command>. Run cm serve to start the MCP server on stdio.

MCP Tools

Tool	Purpose
cx_recall	Priority context for one known scope
cx_search	Content search across wide or unknown scopes
cx_store	Persist a fact, decision, preference, or lesson
cx_deposit	Batch-store conversation exchanges
cx_browse	List entries with filters and pagination
cx_get	Fetch full content for specific entry IDs
cx_update	Partially update an existing entry
cx_forget	Mark entries forgotten so active reads skip them
cx_stats	View store statistics and scope breakdown
cx_export	Export entries as JSON for backup

MCP Examples

cx_recall(query: "auth decisions", scope: {"kind":"path","path":"global/project:helioy"})
cx_recall(scope: {"kind":"cwd_inferred"})
cx_search(query: "auth decisions", scope: {"kind":"all"})
cx_search(query: "scope path", scope: {"kind":"descendants","path":"global/project:helioy"})
cx_search(query: "retry policy", scope: {"kind":"set","paths":["global", "global/project:helioy"]})
cx_store(title: "Use UUIDv7", body: "...", kind: "decision")
cx_store(title: "Repo-scoped lesson", body: "...", kind: "lesson", scope: "global/project:helioy/repo:context-matters")
cx_deposit(exchanges: [{"user":"...","assistant":"..."}])
cx_deposit(exchanges: [{"user":"...","assistant":"..."}], summary: "Conversation about scope routing.", scope: {"kind":"cwd_inferred"})
cx_browse(kind: "decision", scope: {"kind":"path","path":"global/project:helioy"})
cx_browse(scope: {"kind":"cwd_inferred"}, cursor: "opaque-cursor-from-previous-response")
cx_get(ids: ["uuid1", "uuid2"])
cx_update(id: "uuid", title: "Updated title")
cx_update(id: "uuid", body: "Revised body content.", kind: "decision")
cx_forget(ids: ["uuid"])
cx_forget(ids: ["uuid1", "uuid2", "uuid3"])
cx_stats()
cx_export(scope: "global/project:helioy")
cx_export(scope: {"kind":"descendants","path":"global/project:helioy"})

CLI Commands

The CLI reads from the same store as the cx_* MCP tools.

Command	Purpose	Scope input
cm recall	Priority context for one known scope	Optional singular scope selector
cm search	Content search across wide or unknown scopes	Required singular or broad scope selector
cm store	Persist a fact, decision, preference, or lesson	Optional singular scope selector
cm deposit	Batch-store conversation exchanges	Optional singular scope selector
cm browse	List entries with filters and pagination	Optional singular or broad scope selector
cm get	Fetch full content for specific entry IDs	No scope request parameter
cm update	Partially update an existing entry	No scope request parameter
cm forget	Mark entries forgotten so active reads skip them	No scope request parameter
cm stats	View store statistics and scope breakdown	No scope request parameter
cm export	Export entries as JSON for backup	Optional singular or broad scope selector

CLI Examples

cm serve
cm init
cm init --global
cm web --open
cm forget 019d09ed-7a4f-7693
cm recall "auth migration"
cm search "auth migration" --scope '{"kind":"all"}'
cm browse --kind decision -j
cm get 019d09ed-7a4f-7693
cm stats
cm export --scope '{"kind":"descendants","path":"global/project:helioy"}'

Scope Model

Scopes form a hierarchy. Context at broader scopes is visible at narrower scopes.

global                                           cross-project knowledge
global/project:helioy                           project-level decisions
global/project:helioy/repo:context-matters      codebase-specific facts
global/project:helioy/repo:context-matters/session:abc   task context

Public requests select scope through the scope field. The canonical scope path string returned by read tools can be passed directly to write tools.

Singular Selectors

Selector	Request example
canonical path string	{ "scope": "global/project:helioy/repo:context-matters" }
path	{ "scope": { "kind": "path", "path": "global/project:helioy/repo:context-matters" } }
cwd_inferred	{ "scope": { "kind": "cwd_inferred", "cwd": "/path/to/repo" } }
project	{ "scope": { "kind": "project", "project": "helioy" } }
repo	{ "scope": { "kind": "repo", "project": "helioy", "repo": "context-matters" } }
session	{ "scope": { "kind": "session", "project": "helioy", "repo": "context-matters", "session": "abc" } }

Broad Selectors

Selector	Request example
descendants, subtree alias accepted	{ "scope": { "kind": "descendants", "path": "global/project:helioy" } }
set	{ "scope": { "kind": "set", "paths": ["global", "global/project:helioy"] } }
all	{ "scope": { "kind": "all" } }

Tool Scope Boundaries

Tool	Scope request
cx_recall	Optional singular scope selector
cx_search	Required singular or broad scope selector
cx_store	Optional singular scope selector
cx_deposit	Optional singular scope selector
cx_browse	Optional singular or broad scope selector
cx_export	Optional singular or broad scope selector

For cwd based browse resolution, call cx_browse(scope: {"kind":"cwd_inferred","cwd":"/path/to/repo"}). cwd_inferred resolves linked git worktrees to the source repository identity. Persisted entries and export rows include scope_path. Read projections use scope for compact row output.

Two-Phase Retrieval

cx_recall, cx_search, cx_browse return metadata plus snippets. Use cx_get with returned IDs to fetch full body content. This keeps initial responses compact while allowing selective deep reads.

Web UI

Run cm web --open for browser entry management and monitoring. It serves http://localhost:3141/ by default.

Architecture

Five crates, clean separation:

Crate	What it does
cm-core	Domain types, ContextStore trait, query construction. Zero I/O.
cm-store	SQLite adapter via sqlx. WAL mode, FTS5 search, BLAKE3 dedup.
cm-capabilities	Shared request/response types, validation, scope resolution, projections.
cm-cli	CLI binary + MCP server. Tool docs generated from tools.toml.
cm-web	Web monitoring dashboard with Axum and React/Vite. Run cm web --open; default URL: http://localhost:3141/.

Development

Rust 2024 edition. just as task runner.

just check    # fmt + clippy (warnings = errors)
just build    # cargo build --workspace
just test     # cargo test --workspace
just fmt      # rustfmt

License

MIT