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

Tool	Purpose
cx_recall	Priority context for one known scope via ancestor walk
cx_search	Content search across wide or unknown scopes
cx_store	Persist a fact, decision, preference, or lesson
cx_deposit	Batch-store conversation exchanges for continuity
cx_browse	List entries with filters and cursor pagination
cx_get	Fetch full content for specific entry IDs
cx_update	Partially update an existing entry
cx_forget	Soft-delete entries no longer relevant
cx_stats	Store statistics and scope breakdown
cx_export	Export entries as JSON for backup

Scope model

Context is hierarchical. Broader scopes are visible at narrower scopes.

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

Public request inputs select scope with structured scope JSON:

{ "scope": { "kind": "path", "path": "global/project:helioy/repo:fmm" } }

{ "scope": { "kind": "cwd_inferred", "cwd": "/path/to/repo" } }

Other read selectors include subtree, set, and all. cx_recall accepts only path and cwd_inferred; use cx_search for broad content search. cwd_inferred uses git metadata when available, so linked worktrees resolve to the source repository identity instead of the transient worktree directory.

Persisted entries, export rows, response payloads, and internal exact path types include a scope_path field that identifies the exact stored scope of each row.

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.

Development

Rust 2024 edition. just as task runner.

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

License

MIT