Content
# CORDIS v0.1.2
Cordis is an early attempt to give AI agents something they usually lack: a
memory of what actually happened, a way to learn from evidence, and a chance
to approach the next task differently. It is small, model-independent, and
still very much a work in progress.
If the idea interests you, please try it and tell us where it breaks. Bug
reports, awkward edge cases, counterexamples, corrections, and entirely
different design ideas are all welcome. You do not need to arrive with a
finished solution; a clear account of what went wrong or what felt missing is
already useful. Cordis is being developed in the open, and thoughtful
disagreement is part of how we hope to make it better.
Under the hood, Cordis is composed of four runtime packages and one lightweight
installer:
- `cordis-core`: persistent evidence-to-learning loop;
- `cordis-runtime`: structured host bridge, focus state, control mode, compact
model context, and lightweight drift signal.
- `cordis-bridge`: JSON CLI and optional MCP transport for real hosts.
- `cordis-memory`: SQLite cognitive store for events, project/global knowledge,
independently verified patterns, and relationship graph edges.
- `cordis-ai`: installs the complete runtime through one PyPI package.
```text
host or main model
-> structured Task Contract
-> cordis-runtime.begin + cordis-memory retrieval
-> cordis-core.preflight
-> compact model context + control signal
-> host executes
-> cordis-runtime.observe (for plan/tool/test/error events)
-> cordis-runtime.finish
-> cordis-core.feedback
-> later task receives changed cognition
```
Cordis does not interpret arbitrary natural language in v0.1. In a tool-using
agent, the existing main model fills the Task Contract during its normal turn;
no extra model call is required. Planning, Socrates review, tool execution,
HTTP transport, and model-specific adapters remain optional future plugins.
See [cordis-core/ROADMAP.md](cordis-core/ROADMAP.md) for the implementation
roadmap and release boundary.
## Join the conversation
Open an Issue if you find a bug, have a question, or want to challenge a design
decision. For larger ideas, feel free to describe the problem first before
writing code. We would especially like to hear about real host integrations,
learning loops that did not change later behavior, memory that became noisy or
repetitive, and places where the current abstractions simply do not fit.
## Install
Install the complete runtime from PyPI. The `mcp` extra enables the stdio MCP
server used by Codex, Claude Code, OpenCode, and Hermes:
```bash
python -m pip install "cordis-ai[mcp]"
cordis setup codex
```
Restart Codex after setup. CORDIS will then be available as a local MCP server,
with a separate `.cordis` state directory in each project. For CLI-only use,
install the base package with `python -m pip install cordis-ai`, then run
`cordis init`.
Other supported hosts use the same setup command:
```bash
cordis setup claude-code
cordis setup opencode
cordis setup hermes
# Or configure every supported host found on this machine:
cordis setup all
```
Setup installs both the MCP connection and a small managed usage protocol. It
keeps each host in its own writer-safe state directory while project knowledge
remains separated by `project_id`.
Check the current project's state:
```bash
cordis status
```
The JSON CLI is available after installation:
```bat
cordis begin task.json
cordis finish feedback.json
cordis status
```
MCP is an optional transport. Install `cordis-bridge[mcp]` when the host needs
the `cordis_*` MCP tools.
## Local development
The Windows development helper avoids global Python packages, online package
downloads, and PowerShell script-policy issues:
```bat
dev.cmd bootstrap
dev.cmd check
```
`bootstrap` creates `.venv` and installs the local packages without using
the network. `check` runs all standard-library unit tests and rebuilds the
wheels into `outputs\wheels` with the pip cache disabled. It now includes
`cordis-bridge`; its MCP transport remains optional because the base runtime
does not need a model, network, or MCP dependency.
## Releases
Each public release is built from its matching `vX.Y.Z` Git tag and published
through GitHub Actions using PyPI Trusted Publishing. A release is accepted
only after package metadata validation, source and wheel checks, and a clean
installation smoke test.
