Skip to content

Index

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.

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

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

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.1.0/ctx-0.1.0-linux-amd64
chmod +x ctx-0.1.0-linux-amd64
sudo mv ctx-0.1.0-linux-amd64 /usr/local/bin/ctx

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

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

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

Download ctx-0.1.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.1.0/ctx-0.1.0-linux-amd64.sha256

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

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

Build from Source

Requires Go 1.25+:

git clone https://github.com/ActiveMemory/ctx.git
cd ctx
CGO_ENABLED=0 go build -o ctx ./cmd/ctx
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 agents should use this
└── sessions/           # Session snapshots

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"

Note a Learning

ctx add learning "Mock functions must be hoisted in Jest"

Mark Task Complete

ctx complete "user auth"

Check for Stale Context

ctx drift

Next Steps