Skip to main content

Contitext

Project continuity for AI agents.

Keep project state, decisions, checkpoints, and handoffs available across agents, sessions, and machines. Contitext is a small, self-hosted Python service backed by PostgreSQL, with REST and six MCP tools. No LLM API key or embedding service is required.

An agent finishes a session by recording what changed and what comes next. Another agent explicitly selects the same project, reads that context, and continues from the recorded handoff.

v0.5.3 is an early public release. The core service is usable independently. Companion integrations and broader memory features are on the roadmap.

Quick start

Requires Docker with Compose, Python 3.11 or 3.12, and Git.

git clone https://github.com/jessysw/contitext.git
cd contitext
python3 scripts/bootstrap.py
docker compose up --build -d --wait
curl --fail http://127.0.0.1:18791/health/ready
docker compose exec -T app python -m contitext.demo

The bootstrap script creates fresh local credentials in a private .env, seeds a demo project, and preserves existing configuration. The demo writes synthetic events to that project and demonstrates two agents handing work over through the real HTTP API. Its final output includes:

{
  "agent_b_resumed": "demo",
  "next_action": "Implement and test the first endpoint.",
  "idempotent_retry": "passed"
}

The API listens on localhost. PostgreSQL has no published host port. Data persists in a Compose volume; docker compose down stops the service and preserves it. See installation for Python-package setup, administration, backup, and remote access.

Connect an MCP client

The MCP Registry identifier is io.github.jessysw/contitext. The Registry setup guide explains the PyPI/stdio installation and required database configuration.

After the quick start, add this server to a client that supports stdio MCP. Replace the directory with your own absolute checkout path:

{
  "mcpServers": {
    "contitext": {
      "command": "docker",
      "args": ["compose", "--project-directory", "/absolute/path/to/contitext", "exec", "-T", "app", "contitext", "mcp"]
    }
  }
}

Client configuration formats differ. The same command can be used by any stdio MCP client. Load the agent protocol into the client's instruction mechanism and restart its MCP session. This release does not automatically modify your agent settings. The MCP server runs locally inside the existing app container and shares its database.

Tool Purpose
project_bind Explicitly select a project for a caller's conversation scope
project_current Read that scope's current project
context_get Get a bounded project overview, checkpoint, questions, decisions, and handoff
context_record Append a note, decision, question, or checkpoint with provenance
context_handoff Record completed work, current work, blockers, and the next action
context_search Search project events using PostgreSQL full-text search

No project is inferred from the working directory or repository name. Each caller uses a stable conversation scope and explicitly selects a project. Project ACLs are enforced on the server. API contracts and limits describe what the server enforces and what the agent protocol requires.

Commands

Terminal commands use the contitext executable:

contitext --help
contitext --version
contitext migrate
contitext admin seed
contitext serve --host 127.0.0.1 --port 18791
contitext mcp

After installing the agent protocol in your MCP client, use these chat instructions in a conversation with the agent:

!! contitext use demo
!! contitext status
!! contitext search publishing
!! contitext checkpoint Documented the publishing workflow.

!! contitext is the canonical chat prefix. !! ctx is a shortcut, and !! context remains a legacy alias. These are agent instructions, not terminal subcommands. The terminal CLI currently runs and administers the service; it does not implement chat actions such as use, status, or search, and it does not set a global default project. See the command reference for CLI options, compatibility entry points, and conversation scope behavior.

What it includes

  • A durable, append-only event store with caller identity and source provenance.
  • Reader, writer, and owner project ACLs shared by REST and MCP.
  • Idempotent retries; conflicting reuse of an event key is rejected.
  • PostgreSQL full-text retrieval with pagination, without an embedding dependency.
  • Optional Markdown projection for local inspection and note-taking tools.
  • Synthetic tests for isolation, concurrency, restart recovery, projection, and real MCP stdio calls.

Use Contitext when you need explicit project continuity across tools and machines. It does not automatically capture every conversation, consolidate memories, build a knowledge graph, or decide which facts are true. A project handoff is the latest handoff for the whole project, not a task scheduler or a conflict-resolution system.

Development

See CONTRIBUTING.md for the isolated PostgreSQL test setup. See SECURITY.md for trust boundaries and vulnerability reporting. Repository: jessysw/contitext.

License

Apache License 2.0.

Metadata

Release files for contitext 0.5.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for contitext 0.5.3
File Size Uploaded Provenance Actions
contitext-0.5.3.tar.gz 61.1 kB With provenance Details for contitext-0.5.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for contitext 0.5.3
File Interpreter ABI Platform Actions
contitext-0.5.3-py3-none-any.whl Python 3 none any Details for contitext-0.5.3-py3-none-any.whl

Total release size: 94.9 kB

Release files / contitext-0.5.3.tar.gz

Download URL contitext-0.5.3.tar.gz
Size 61.1 kB
Tags Source
SHA-256 checksum
How to use checksums
96edeb09f264a38afc126a1fc03ccbc14a1dc3ff8a46a8b26a2bd0b226ce36e6
BLAKE2b-256 checksum
How to use checksums
1e0f534881f4164cb8a273d6b6fc585b516a6bc1cd5b3ae0e5a49b4d9bf6fd9f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / contitext-0.5.3-py3-none-any.whl

Download URL contitext-0.5.3-py3-none-any.whl
Size 33.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
561bf3a822ebecfefd5a023add3e334da4d44a696c67f7c6c363d08519d9cb49
BLAKE2b-256 checksum
How to use checksums
2da02b6396b50927c33b4086cf16361772aeb7090303dd58280a50e8a555a16e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for contitext 0.5.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for contitext-0.5.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page