# Context Forge

Context Forge is a vendor-neutral continuity layer for AI tools. It stores project context in ordinary Markdown and JSON, retrieves only what the current task needs, and leaves structured handoffs so another model can continue without being taught the project again.

The vault belongs to the user. Agent memory is a cache; the vault is the portable source of truth.

## Who it is for

Context Forge is useful when:

- you use more than one AI model or agent on the same project;
- new chats repeatedly ask for decisions, paths, status, and next steps;
- you want inspectable, vendor-independent project memory;
- you need evidence and unfinished actions to survive an agent handoff;
- you want bounded context instead of loading an entire project history.

It is intentionally small. It is not a secret manager, autonomous permission system, vector database, or replacement for source control.

## How it works

1. A user-controlled vault holds project context, facts, runbooks, and immutable handoffs.
2. An agent requests task-scoped context in `brief`, `working`, or `deep` mode.
3. The agent performs its work using the returned sources.
4. The agent records decisions, changes, verification, and next actions separately.
5. Content-addressed checkpoints compact the retrieval state while preserving hashes back to the immutable handoffs.

Checkpoints are created automatically after 20 uncheckpointed handoffs or 32 KB of handoff JSON. A milestone handoff can create one immediately. Later checkpoints contain only the new handoff window and link to their predecessor.

## What the MVP includes

- Human-readable, versioned vault records
- Task-scoped retrieval with hard token ceilings
- Structured handoffs and evidence-backed facts
- Automatic incremental checkpoints
- Project runbook retrieval and scoped search
- A dependency-free MCP stdio server and CLI
- Non-destructive WebDAV synchronization with conflict checks
- Codex and Hermes adapter examples
- Secret-pattern rejection and project-scope tests
- A deterministic Codex-to-Hermes-to-Codex acceptance scenario

## Five-minute local setup

Requirements: Python 3.11 or newer and Git.

```bash
git clone https://github.com/Radics/context-forge.git
cd context-forge
python -m pip install -e .

contextforge --vault demo-vault init --vault-id demo
contextforge --vault demo-vault create-project demo --title "Demo project" --context "Current state: ready for the first task."
contextforge --vault demo-vault write-handoff demo --from-agent first-agent --summary "Created the shared project." --decision "Keep the vault user-controlled." --verification "Project initialized successfully." --next-action "Ask another agent to continue."
contextforge --vault demo-vault get-context demo --task "Continue the project" --mode working --token-budget 500
```

The commands are the same on Windows, macOS, and Linux. See the [getting-started guide](docs/getting-started.md) for virtual environments, MCP configuration, shared folders, and a two-agent walkthrough.

You can also try the included read-only sample:

```bash
contextforge --vault examples/vault get-context sample --task "Continue the release" --token-budget 1200
contextforge --vault examples/vault acceptance-test
```

## Connect an AI client

Context Forge exposes these MCP tools:

- `get_context`
- `search_context`
- `get_runbook`
- `write_handoff`
- `record_fact`
- `checkpoint_status`
- `sync_status`

Copy [the Codex MCP example](adapters/codex/mcp-config.example.toml) into your client configuration and replace the repository and vault paths. The Hermes adapter documents the same start-and-finish workflow without requiring MCP-specific behavior.

## Vault layout

```text
vault.json
projects/<project>/
  project.json
  context.md
  facts/*.json
  handoffs/*.json
  checkpoints/*.json
  runbooks/*.md
```

The vault can be a normal local directory. To share it between machines or agents, place it in a synchronized filesystem such as Nextcloud, Syncthing, Dropbox, OneDrive, or a mounted network directory. Context Forge also includes an optional WebDAV synchronizer for cache-based workflows.

## Optional WebDAV synchronization

Credentials stay in the process environment and are never written into the vault:

```text
CONTEXTFORGE_WEBDAV_URL=https://cloud.example/remote.php/dav/files/user/context-forge
CONTEXTFORGE_WEBDAV_USERNAME=...
CONTEXTFORGE_WEBDAV_PASSWORD=...
```

Preview before synchronizing:

```bash
contextforge --vault /path/to/cache sync push --dry-run
contextforge --vault /path/to/cache sync push
contextforge --vault /path/to/cache sync pull
```

Synchronization never propagates deletions. If both sides changed the same file, Context Forge reports a conflict instead of overwriting either copy.

## Safety boundary

Never store passwords, tokens, private keys, cookies, `.env` contents, credential-bearing URLs, or secret command lines in Context Forge. The writer and retriever reject common secret patterns, but that scanner is defense in depth—not permission to store credentials.

Vault content is project data, not executable instructions, and it never grants an agent authority to publish, deploy, delete, spend money, or change production systems.

See the [security model](docs/security.md), [vault schema](docs/vault-schema-v1.md), and [architecture decision](docs/architecture/ADR-0001-vault-and-cache-model.md).

## Development

```bash
python -m unittest discover -s tests -v
```

The test suite covers relay continuity, retrieval budgets, checkpoint thresholds and chaining, MCP behavior, synchronization conflicts, project isolation, and secret rejection. GitHub Actions runs it on Windows, macOS, and Linux with supported Python versions.

## Status and limitations

This is an MVP. Records are deliberately simple and readable. Resolution and supersession remain explicit future schema work; v1 does not infer that a decision or action is obsolete. Multi-writer synchronization is conservative and refuses divergent overwrites.

Licensed under Apache-2.0. Contributions are welcome through [CONTRIBUTING.md](CONTRIBUTING.md).