Upgrading ctx

Upgrading ctx¶

New versions of ctx may ship updated permissions, CLAUDE.md directives, Makefile targets, or plugin hooks and skills.

A version upgrade means:

• getting the new binary,
• regenerating the infrastructure it installs into your project,
• and updating the ctx plugin (if using Claude Code).

What Changes Between Versions¶

ctx init generates two categories of files:

Infrastructure is regenerated by ctx init and plugin updates. Knowledge files are yours and should never be overwritten.

Upgrade Steps¶

1. Back Up¶

cp -r .context .context.bak
cp -r .claude .claude.bak
cp CLAUDE.md CLAUDE.md.bak
cp PROMPT.md PROMPT.md.bak

2. Install the New Version¶

Build from source or download the binary:

cd /path/to/ctx-source
git pull
make build
sudo make install
ctx --version   # verify

3. Reinitialize¶

ctx init --force --merge

• --force regenerates infrastructure files (permissions, Makefile.ctx).
• --merge preserves your content outside ctx markers in CLAUDE.md and PROMPT.md.

4. Restore Knowledge Files¶

cp .context.bak/TASKS.md          .context/
cp .context.bak/DECISIONS.md      .context/
cp .context.bak/LEARNINGS.md      .context/
cp .context.bak/CONVENTIONS.md    .context/
cp .context.bak/ARCHITECTURE.md   .context/
cp .context.bak/GLOSSARY.md       .context/
cp .context.bak/CONSTITUTION.md   .context/
cp .context.bak/AGENT_PLAYBOOK.md .context/

Also restore any data directories:

# Session and journal data (if present)
cp -r .context.bak/sessions/ .context/sessions/ 2>/dev/null
cp -r .context.bak/journal/  .context/journal/  2>/dev/null

# Scratchpad key (never regenerate — you'd lose encrypted data)
cp .context.bak/.scratchpad.key .context/ 2>/dev/null
cp .context.bak/.scratchpad.enc .context/ 2>/dev/null

5. Update the ctx Plugin¶

If you use Claude Code, update the plugin to get new hooks and skills:

# From source
claude /plugin install ./internal/tpl/claude

# Or update from marketplace
claude /plugin install ctx@activememory-ctx

6. Review Custom Settings¶

If you added custom permissions to .claude/settings.local.json beyond what ctx init provides, diff and merge:

diff .claude.bak/settings.local.json .claude/settings.local.json

Manually add back any custom entries that the new init dropped.

7. Verify¶

ctx status          # context files intact
ctx drift           # no broken references

8. Clean Up¶

Once satisfied, remove the backups:

rm -rf .context.bak .claude.bak CLAUDE.md.bak PROMPT.md.bak

What If I Skip the Upgrade?¶

The old binary still works with your existing .context/ files. But you may miss:

• New plugin hooks that enforce better practices or catch mistakes;
• Updated skill prompts that produce better results (via plugin update);
• New .gitignore entries for directories added in newer versions;
• Bug fixes in the CLI itself.

Context files are plain Markdown: They never break between versions.

The surrounding infrastructure is what evolves.

Quick Reference¶

# Full upgrade (recommended)
cp -r .context .context.bak && cp -r .claude .claude.bak
# install new ctx
ctx init --force --merge
cp .context.bak/{TASKS,DECISIONS,LEARNINGS,CONVENTIONS,\
  ARCHITECTURE,GLOSSARY,CONSTITUTION,AGENT_PLAYBOOK}.md .context/
cp .context.bak/.scratchpad.key .context/ 2>/dev/null
rm -rf .context.bak .claude.bak