Skip to content

Getting Started

ctx

ctx

ctx (Context) is a file-based system that enables AI coding assistants to persist project knowledge across sessions. Instead of re-explaining your codebase every time, context files let AI tools remember decisions, conventions, and learnings:

  • A session is interactive.
  • ctx enables cognitive continuity.
  • Cognitive continuity enables durable, symbiotic-like human–AI workflows.

Community

Open source is better together.

Help ctx Change How AI Remembers

If the idea behind ctx resonates, a star helps it reach engineers who run into context drift every day.

→ https://github.com/ActiveMemory/ctx

ctx is free and open source software, and contributions are always welcome and appreciated.

Join the community to ask questions, share feedback, and connect with other users:

  • Discord: Chat, get help, share your workflows
  • GitHub: Star the repo, report issues, contribute

Why?

Most AI-driven development fails not because models are weak—they fail because context is ephemeral. Every new session starts near zero:

  • You re-explain architecture
  • The AI repeats past mistakes
  • Decisions get rediscovered instead of remembered

ctx solves this by treating context as infrastructure: files that version with your code and persist across sessions.

Installation

Download pre-built binaries from the releases page.

curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.2.0/ctx-0.2.0-linux-amd64
chmod +x ctx-0.2.0-linux-amd64
sudo mv ctx-0.2.0-linux-amd64 /usr/local/bin/ctx

curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.2.0/ctx-0.2.0-linux-arm64
chmod +x ctx-0.2.0-linux-arm64
sudo mv ctx-0.2.0-linux-arm64 /usr/local/bin/ctx

curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.2.0/ctx-0.2.0-darwin-arm64
chmod +x ctx-0.2.0-darwin-arm64
sudo mv ctx-0.2.0-darwin-arm64 /usr/local/bin/ctx

curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.2.0/ctx-0.2.0-darwin-amd64
chmod +x ctx-0.2.0-darwin-amd64
sudo mv ctx-0.2.0-darwin-amd64 /usr/local/bin/ctx

Download ctx-0.2.0-windows-amd64.exe from the releases page and add it to your PATH.

Verifying Checksums

Each binary has a corresponding .sha256 checksum file. To verify your download:

# Download the checksum file
curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.2.0/ctx-0.2.0-linux-amd64.sha256

# Verify the binary
sha256sum -c ctx-0.2.0-linux-amd64.sha256

On macOS, use shasum -a 256 -c instead of sha256sum -c.

Build from Source

Building from the source gives you the latest features and bug fixes; however, it also means you will be using an unreleased version of ctx that has not been fully tested.

Want to help test the latest features?

If you like living on the edge and want to test the latest features before they are released, then building from source is the way to go.

Requires Go 1.25+:

git clone https://github.com/ActiveMemory/ctx.git
cd ctx
make build
sudo make install
# or:
# sudo mv ctx /usr/local/bin/

Verify installation:

ctx --version

Quick Start

1. Initialize Context

cd your-project
ctx init

This creates a .context/ directory with template files and configures AI tool hooks (for Claude Code).

2. Check Status

ctx status

Shows context summary: files present, token estimate, and recent activity.

3. Start Using with AI

With Claude Code, context loads automatically via hooks. For other tools, paste the output of:

ctx agent --budget 8000

4. Verify It Works

Ask your AI: "Do you remember?"

It should cite specific context: current tasks, recent decisions, or previous session topics.

What Gets Created

.context/
├── CONSTITUTION.md     # Hard rules — NEVER violate these
├── TASKS.md            # Current and planned work
├── CONVENTIONS.md      # Project patterns and standards
├── ARCHITECTURE.md     # System overview
├── DECISIONS.md        # Architectural decisions with rationale
├── LEARNINGS.md        # Lessons learned, gotchas, tips
├── GLOSSARY.md         # Domain terms and abbreviations
├── DRIFT.md            # Staleness signals
├── AGENT_PLAYBOOK.md   # How AI tools should use this
└── sessions/           # Session snapshots

.claude/                # Claude Code integration (if detected)
├── hooks/              # Auto-save and enforcement scripts
├── commands/           # ctx slash command definitions
└── settings.local.json # Hook configuration

See Context Files for detailed documentation of each file.

Common Workflows

Add a Task

ctx add task "Implement user authentication"

Record a Decision

ctx add decision "Use PostgreSQL for primary database" \
  --context "Need a reliable database for production" \
  --rationale "PostgreSQL offers ACID compliance and JSON support" \
  --consequences "Team needs PostgreSQL training"

Note a Learning

ctx add learning "Mock functions must be hoisted in Jest" \
  --context "Tests failed with undefined mock errors" \
  --lesson "Jest hoists mock calls to top of file" \
  --application "Place jest.mock() before imports"

Mark Task Complete

ctx complete "user auth"

Check for Stale Context

ctx drift

Next Steps