contexer 0.6.0

MCP server that captures and retrieves architectural decisions and context for Claude Code sessions

contexer.ai · Discord · Docs

Contexer is an MCP server for Claude Code that remembers decisions made during a session and replays them at the start of every future session.

---

The problem

Every Claude Code session starts fresh. No memory of what was decided yesterday, last week, or in a different window.

You end up repeating yourself constantly: "we use uv not pip", "always write tests before committing", "we chose Postgres because of transactions". CLAUDE.md files help, but they need manual upkeep and go stale. The reasoning behind decisions disappears when the session ends.

---

Install

uv tool install contexer
contexer install

Restart Claude Code and open any git repo. That's it.

See docs/install.md for verification, update, and uninstall steps.

---

How it works

Contexer runs silently in every session. You don't interact with it directly.

First time in a repo — Claude includes a brief offer at the top of its first response. The offer adapts to how well you know the repo, judged from its git history:

• The repo has commits from you → pick quick (one question) or full (guided setup).
• No commits from your git email (e.g. a freshly cloned project) → Contexer suggests scan: it reads the code and docs instead of asking questions you can't answer.
• Can't tell → it simply asks how well you know the repo.

Whatever was detected, all options (quick / full / scan / skip) stay available — reply with the one you want. And if your first message is itself a newcomer question ("what is this repo doing?"), Contexer skips the menu entirely and just confirms it should scan before answering you. Claude answers your original request either way.

Every session after that — before your first message, Claude reads:

Contexer: 3 constraints, 2 conventions loaded. 8 arch/patterns will be loaded on demand.

Constraints and conventions are injected immediately — they apply to every task. Architecture and pattern decisions load on demand when the task needs them.

As you work, Claude stores decisions automatically. If it misses something, say "store that as a constraint" and it's saved.

Resumed sessions (--resume / --continue) don't repeat any of this — the context is already in the conversation. And if you installed Contexer mid-project, resuming an old session makes Claude mine that conversation for decisions already made and store them, no questions asked.

---

CLI reference

Command	Description
contexer install	Connect Contexer to Claude Code
contexer status	Show connection status, store size, current repo; warns about corrupt config files, cleans stale temp files, and notifies when a newer version is on PyPI
contexer reinstall	Re-sync after a Claude Code update
contexer uninstall	Disconnect; context store is kept
contexer uninstall --purge	Remove everything including ~/.contexer/
contexer version	Print installed version
contexer help	Show all commands and flags

---

Decision types

Type	What it captures	Loaded at session start
constraint	Hard rules — "never commit untested code"	Yes
convention	Team standards — "use uv not pip", "conventional commits"	Yes
architecture	Structural choices — "REST over GraphQL for the external API"	On demand
pattern	Recurring approaches — "validate at the boundary"	On demand

---

Storing and querying decisions

"store that as a constraint"
"save this as a convention: always use uv not pip"
"what decisions did we make about postgres?"
"show all constraints"
"delete the postgres decision"
"save this as a global constraint: always use conventional commits"

Global decisions apply across all repos — use them for commit style, branch naming, anything that travels with you.

Note: Your first prompt each session is also captured as the current task. A first prompt phrased as a clear directive ("always update docs before committing") is still auto-saved as a constraint — but a rule phrased indirectly may slip past the detector, so follow up with "store that as a constraint" to be sure.

Edit the store directly if you prefer — it's plain JSON at ~/.contexer/.

---

Performance

Context processing runs before Claude generates a response, not during it. It adds nothing to response time.

Operation	Time
Hit (decision found)	0.3–0.5ms
Miss (no match)	~0ms
Session start load	~1ms

Token cost is paid once at session start. Every prompt after that is free.

Pre-loaded rules	Tokens
5	~125
10	~250
25	~625

~26 tokens per rule, fixed regardless of store size. On prompts unrelated to stored decisions, Contexer skips entirely — no read, no tokens.

---

Troubleshooting

Decisions aren't being stored automatically. Say "store that decision" to save it manually.

A decision isn't appearing at session start. Constraints and conventions load at session start. One added mid-session shows up next time.

A new decision was silently skipped. Content too similar to an existing entry is rejected as a duplicate. Rephrase to include what specifically changed.

No context at session start on a new repo. Claude will offer bootstrap setup. Say yes to capture initial decisions — all future sessions will have context.

---

Contributing

Bug reports, fixes, and documentation improvements are welcome. See CONTRIBUTING.md for setup, code style, and the PR process.

Questions? Discord.

---

License

MIT — see LICENSE for full terms.

The Contexer name and logo are trademarks of Contexer.ai. The MIT license does not grant rights to use the name or logo in a way that implies official affiliation.