Your agent shouldn’t start from zero.
Keep the decisions, constraints, and lessons that matter close to your code. One local project memory, shared by the coding tools you already use.
A memory layer for
your existing workflow.
Integration options, not endorsements. Capabilities and verification differ by host.
Less re-explaining.
More building.
A new session can read your files. SupraCortex also gives it the decisions behind them—and a clear place to pick up.
Keep the why.
Not the whole conversation.
Store a decision with a reference to the file that supports it. The important part outlives the session that produced it.
cortex_recordSample projectUse server-side sessions.
We need immediate session revocation.
docs/architecture/auth.md.supracortex/Structured project knowledge. No full transcript stored.
The relevant parts.
Within a budget.
For “continue the authentication work,” retrieve the decisions and constraints that matter. Each selected memory comes with a reason.
cortex_contextSample projectUse server-side sessions.Reason: authentication architecture
180 tokensKeep the public auth API unchanged.Reason: active implementation constraint
210 tokensAdd a logout regression test.Reason: unfinished task from the handoff
120 tokensSelected context should still be verified against the source.
Pick up the work.
Not the explanation.
Capture the goal, completed work, tests, risks, and next actions. Resume that handoff in a later session, or from another connected host.
cortex_handoffSample projectResume the bounded capsule with cortex_resume.
Decisions you shouldn’t repeat.
The approach you chose, and why.
Lessons you shouldn’t lose.
What failed, and the constraints that still apply.
A place to pick up.
Completed work, open risks, and what comes next.
Useful memory
can be checked.
Sources change. Memory should admit it. Evidence mismatches mark an entry stale; contradictions are surfaced rather than quietly overwritten.
Refreshing evidence doesn’t make a memory active again. That takes an explicit approval.
Read the trust and security modelUse server-side sessions.
- Source
docs/architecture/auth.md- Evidence
- File hash matches
- Status
- Active
The recorded evidence matches the source. Try changing the source to see what happens.
Different tools.
One project memory.
The core runs as a local MCP server. The native OpenCode adapter adds lifecycle hooks and additional orchestration-support tools.
| Your coding tool | Connection | Verification | Installation |
|---|---|---|---|
| OpenCode | Native adapter + MCP | V1 live-tested · V2 fixture-tested | Set up → |
| Claude Code | MCP stdio | Wiring live-verified | Set up → |
| Codex CLI | MCP stdio | Wiring live-verified | Set up → |
| Other MCP clients | Standard server configuration | Documented · verify in your client | Set up → |
All hosts must use the same project root. Wiring verification is not a full model-session test. Pi is experimental and requires an upstream patch. Check tested versions and limitations ↗
Install it.
Keep building.
Choose your coding tool. Install SupraCortex, initialize it in your project, then check the connection.
Full installation guide# Install, then enter your project npm install -g supracortex cd /path/to/your/project # Initialize project wiring and verify supracortex init --yes supracortex doctor
Initialization detects supported hosts and writes the project-local configuration it owns. Run it again for each project you want to remember.
Before you
plug it in.
The core is small on purpose. Here’s what it does—and what it doesn’t.
How is this different from an AGENTS.md file?
Keep using AGENTS.md for project instructions. SupraCortex adds structured, source-backed memories, task-specific retrieval, explicit review, and session handoffs. It complements your instructions rather than replacing them.
Can I switch coding tools and keep the memory?
Yes, when both hosts use the same project-local .supracortex/ store. Start the MCP server from the project root or set SUPRACORTEX_ROOT. Memory is shared; lifecycle hooks and available tools still differ by host. This is not cloud sync between machines.
Does anything leave my machine?
SupraCortex stores runtime data locally. Its optional Jev decision layer is enabled but makes no provider call without credentials; supplying a decision-provider key can send bounded task snippets to that provider. Your coding host may separately send retrieved context to its model. See the security model before connecting sensitive projects.
Do I need embeddings, an API key, or a subscription?
The deterministic core requires no embeddings, vector database, or decision-provider API key. The project is MIT licensed. Your coding tool, model provider, or optional decision provider may have its own costs.
What happens when a memory gets outdated?
Changed evidence marks a memory stale. Refreshing its evidence updates file hashes but does not reactivate it: that requires explicit approval. Age alone does not change a memory’s status. Treat retrieved context as guidance to verify, not guaranteed truth.
Does it work on Windows?
Use the Node.js entrypoint for the MCP server, such as node node_modules/supracortex/dist/cli.js mcp with a local install. The supracortex-mcp Bash launcher is macOS/Linux only. The installation guide covers host configuration.
Your memory.
Nothing hidden.
Read the code. Inspect the retrieval. Report what doesn’t work. SupraCortex is an open-source project, not a black box around your context.
Local-first project memory.
MCP server, CLI, and an optional OpenCode adapter.