ContxOS for Claude Code: Project Memory Beyond CLAUDE.md

A division of labor

• CLAUDE.md: short rules the agent needs on every turn, such as build commands, conventions and "never do X".
• ContxOS: everything else, such as why the auth flow works the way it does, what broke last time the cache was changed, the release procedure, and the state of the migration you paused on Friday.

A good rule: if the agent needs it on every turn, it goes in CLAUDE.md. If it needs it only for certain tasks, it goes in ContxOS, where it is found by search.

Commands installed in your repo

After "sync ide", the ContxOS commands appear as slash commands in Claude Code: /contxos to search or route a phrase, /handoff and /finish to close a session, /workflow to build or edit procedures, /dream for upkeep, and /blinders to pull a drifting agent back to the knowledge base before it reads files blind. They are generated and versioned, and the agent offers a re-sync when a newer version exists.

Search the knowledge base before the files

Reading files is expensive and misses history. The file shows what the code does, not why it was written that way or what was tried before. The ContxOS commands tell the agent to search the knowledge base first, then open the files the knowledge base points to. On a large codebase this saves context and avoids repeating old mistakes.

What to ask your agent

With ContxOS connected to Claude or another MCP client, requests like these work as written:

Limits and requirements

• Claude Code must be connected to ContxOS as a remote MCP server (see the setup guide).
• Slash commands are generated per project and per environment. Re-sync after switching projects if the commands look stale.

Frequently asked questions