SupraCortex
Project memory for coding agents.
Local-first project memory for coding agents: an MCP stdio server, CLI, optional OpenCode adapter, deterministic lexical retrieval, JSONL by default, opt-in SQLite/FTS5, and evidence references that can go stale.
- Role
- Creator
- Stack
- Node.js 22.6+
- TypeScript
- MCP SDK
- Zod
- SQLite/FTS5
- JSONL
- Biome
Context
Coding agents often start from scratch because project memory is unreliable. SupraCortex offers local memory an agent can query through MCP, without depending on a remote service.
The project is released under the MIT license. It favours reproducible results and explicit evidence references.
Constraints
- Local-first operation had to remain possible without a database.
- Retrieval had to be deterministic so the same queries return the same results.
- Evidence references had to stay honest, including when they go stale.
Decisions
Lexical retrieval rather than embeddings
Search relies on deterministic lexical retrieval, with no embedding model or external service.
Trade-offLess semantic recall, but reproducible results and entirely local operation.
JSONL by default, SQLite/FTS5 opt-in
Default storage remains a readable JSONL file. SQLite and FTS5 are available when volume or search justifies it.
Trade-offTwo storage modes to maintain, but the simple path stays the default.
Evidence references that can age
Each memory points back to its source. The system flags a reference that is no longer valid instead of presenting it as certain.
Trade-offThe product exposes uncertainty, which asks more of the agent and the user.
Method
Specify
The MCP contract, the JSONL format and the lexical retrieval rules defined before writing the server.
Orchestrate
Agents on separate scopes (server, CLI, OpenCode adapter), with a shared schema.
Verify
Behaviour reviewed and tested, including how an evidence reference goes stale.
Architecture
Interface
- CLI
- MCP stdio
- OpenCode adapter
Application
- Lexical retrieval
- Evidence references
- Zod validation
Data & runtime
- Node.js 22.6+
- TypeScript
- JSONL
- SQLite/FTS5
Local memory, queryable by the agent, readable by the human.
Delivered
- The MCP stdio server and CLI.
- Deterministic lexical retrieval and evidence references.
- Default JSONL storage and optional SQLite/FTS5.
- The optional OpenCode adapter and MIT release.
What I would do differently
I would add an explicit migration path between JSONL and SQLite, to make moving from one store to the other more predictable.