context-rail 1.0.0

Context Rail — lightweight file-based project context store for AI agents.

Context Rail

A lightweight, file-based context store for AI agents working in a project.

Context Rail keeps the project's state in a .context-rail/ directory at the workspace root: plain Markdown files with JSON frontmatter. Git is the history — commit the directory and every context change is versioned. No database server, no SQLite, no web UI; the files are the store.

Context Rail gives agents a way to onboard, capture project facts, find context, and hand off cleanly — with 13 MCP tools (12 workflow tools + a health check) and a small CLI.

Install

pip install context-rail

Requires Python 3.11+. The only runtime dependency is mcp>=1.0.0.

Initialize a project

cd /path/to/your/project
ctx-rail init --name "My Project"

This creates .context-rail/ and generates an AGENTS.md in the project root.

The store layout

.context-rail/
├── project.json   # project metadata (name, state, current phase)
├── roadmap.md     # vision, intent, success criteria, phase overview
├── phases/        # one file per phase
├── decisions/     # one file per decision
├── notes/         # one file per captured fact
├── areas/         # one file per area (structural axis surviving across phases)
├── groups/        # one file per group (named collections of any entity ids)
├── status.md      # append-only status timeline
├── handoff.md     # the single living handoff for the project
├── current.md     # project momentum: Goal / Current Direction / Blockers / Next Validation
├── activity.log   # append-only activity log (JSONL)
└── artifacts/     # committed derived documents (overview.md, overview.html)

Connect your MCP client

ctx-rail config          # JSON format
ctx-rail config --client codex  # TOML format for Codex

The printed config points your MCP client at the local python -m context_rail serve command.

The tools

Tool	Purpose
context_get	purpose-scoped context: onboard / status / decisions / handoff / phase / free-form search
context_project	resolution engine: minimum complete context for a seed (phase/area/decision/file/tag/cursor/project) under a policy
roadmap_show	read the roadmap and phases
roadmap_edit	add, update, reorder, or delete phases
status_update	append a status entry
handoff_set	write the project handoff
current_set	write project momentum (Goal / Current Direction / Known Blockers / Next Validation)
decision_create	record a decision
decision_edit	update or delete a decision
note_add	capture a project fact
note_find	search notes (query, kind, tags, phase)
note_edit	update or delete a note
area_add / area_edit / area_show	manage areas (the structural axis)
group_add / group_edit / group_show	manage groups (named collections of any entity ids)
activity	recent activity log entries
health	server health status (pid, version)

CLI commands

ctx-rail init          # initialize .context-rail/ + AGENTS.md
ctx-rail serve         # start the MCP server (stdio)
ctx-rail config        # print MCP client config
ctx-rail status        # project state, last status, handoff age, counts
ctx-rail doctor        # health check: files, schema, orphan references
ctx-rail update        # upgrade instructions
ctx-rail capture       # auto-capture from git history, or CI/release events
ctx-rail session-start # capture catch-up + digest + cursor advance
ctx-rail overview      # render the 15-section overview document (artifacts/overview.md)
ctx-rail render        # render the project understanding web page (artifacts/overview.html)

Daily workflow

ctx-rail init                                    # once per project (scaffolds the store)
context_get(purpose="onboard")                   # full snapshot at session start
note_add(content="...", kind="reference", tags="...")   # capture as you work
decision_create(question="...", choice="...", rationale="...")
status_update(state="active", summary="...")    # update status
current_set(content="...")                      # keep project momentum current
handoff_set(content="...")                      # before you leave

Project facts go into notes (note_add). Decisions, status, and the handoff are kept current. context_get with a free-form purpose searches notes and decisions when you need specific context. context_project(seed=..., policy=...) gives the resolution engine's minimum-complete-context projection for a task (phase, area, decision, file, tag, cursor, or the whole project).

What Context Rail is not

Context Rail is not a project-management tool. It does not assign tasks, track estimates, or run sprints. Context Rail is not a code indexer. It does not search your source code — use your code intelligence tools for that. Context Rail is not a governance system. It does not enforce rules, gates, or approvals — it stores and retrieves context.

Development / Testing

Run the test suite with the project venv:

.venv\Scripts\python.exe -m pytest tests/ -v

Or, in a fresh environment:

pip install -e ".[test]"
pytest tests/ -v

ctx-rail doctor in an initialized project is a quick health check — it validates the store layout, file schemas, and orphan references. python -m compileall src verifies the source compiles.

License

MIT