Metadata-Version: 2.4
Name: context-rail
Version: 1.0.0
Summary: Context Rail — lightweight file-based project context store for AI agents.
License: MIT
Project-URL: Repository, https://github.com/nguyenhoanhson797/Context-Rail
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-asyncio>=0.24; extra == "test"
Dynamic: license-file

# 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

```bash
pip install context-rail
```

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

## Initialize a project

```bash
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

```text
.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

```bash
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

```bash
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

```text
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:

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

Or, in a fresh environment:

```bash
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
