Curion

Project-local memory layer for AI agents, exposed as a Model Context Protocol (MCP) stdio server.

Curion gives your AI agent a persistent memory of the project it is working in. Across sessions it can remember design decisions, architecture choices, team conventions, and anything else you choose to store — and recall the relevant pieces when you ask.

It runs as a local MCP stdio server that any compatible client can spawn. Each project has its own private store at .curion/; memories are never sent to a shared backend.

The public MCP API (the two tools, their strict input schemas, and the public text / structuredContent surfaces) is stable and frozen.

Why Curion

• Persistent, project-local memory. Design decisions, conventions, and "things to remember" survive across sessions inside .curion/.
• Two tools, one surface. remember(text) stores a piece of project memory; recall(text) retrieves the relevant pieces. Each takes a single text parameter — no kinds, states, filters, or knobs on the public API.
• Private by default. Memory lives in your project. Memories are never sent to a shared backend. Mark a project private with one line of JSON and it will never be surfaced by cross-project retrieval.
• Pluggable providers. OpenAI-compatible (default) or Anthropic. Add a fallback provider, or enable opt-in semantic retrieval.
• Stable, frozen public API. The two tools, their strict input schemas, and the public text / structuredContent surfaces are stable and frozen.

Quick start

Requires Node.js >= 22 (matches the engines.node field in package.json).

# Recommended: install globally so the `curion` binary is on your PATH.
npm install -g @geanatz/curion

The package installs a curion CLI binary which is the MCP stdio server entrypoint. When an MCP client spawns it, curion speaks JSON-RPC over stdin/stdout and writes all logs to stderr. It is not an interactive CLI — always start it through an MCP client that manages the stdio transport.

stdio transport only. Curion only exposes the stdio transport. It does not open any network sockets and does not run as a long-lived process you start from a terminal. The MCP host (your client) spawns curion as a subprocess and is responsible for the network boundary. See Security model.

Register with your MCP client

Claude Code is the recommended MCP client. Registering Curion with --scope project keeps the configuration inside the repo (via .mcp.json), so every contributor gets the same server setup without touching their global MCP config.

claude mcp add --scope project --transport stdio curion -- curion

For Codex CLI, OpenCode, Claude Desktop, and other clients, see MCP client setup.

Provide a provider

Curion has no built-in provider defaults. Configure a primary provider in your shell environment before launching the MCP client (Curion does not load .env files):

# OpenAI-compatible (default)
export CURION_PRIMARY_API_KEY=sk-...
export CURION_PRIMARY_BASE_URL=https://api.openai.com/v1
export CURION_PRIMARY_MODEL=your-model-id

# Anthropic
export CURION_PRIMARY_API_FORMAT=anthropic
export CURION_PRIMARY_API_KEY=sk-ant-...
export CURION_PRIMARY_MODEL=your-model-id

Full env-var reference: Configuration.

Other MCP clients

Curion works with any MCP client that can spawn a stdio server. Full configuration snippets and caveats:

• Claude Code (recommended) — claude mcp add --scope project --transport stdio curion -- curion.
• OpenAI Codex CLI — config.toml or codex mcp add.
• OpenCode — opencode.json.
• Claude Desktop — generic stdio client.
• Pi Coding Agent — Pi has no native MCP support; use Claude Code, Codex CLI, or OpenCode instead.
• Any other stdio MCP client — spawn curion with provider env vars in the environment.

Example prompts

Once your MCP client is connected, the agent can call remember and recall directly. The strings below are exactly what an agent would pass as the text parameter.

Store a design decision:

remember: "We chose SQLite (better-sqlite3) over Postgres for the memory
store because the project is single-host and the binary footprint is
smaller. Migration to a hosted DB is not in scope."

Store a convention:

remember: "Conventions: TypeScript strict mode on, 2-space indent,
double-quoted strings, Biome for lint+format. See CONTRIBUTING.md."

Recall later:

recall: "Why did we pick SQLite over Postgres for the memory store?"

Ask about a convention:

recall: "What are the project's formatting and lint conventions?"

The agent receives a calm prose text content block plus a structured discriminated shape on structuredContent. Discriminate with structuredContent.status (saved / answered / weak_match / no_memory / rejected / provider_error). When clarification_needed is present, the agent must ask the user the question verbatim — see the API reference.

Key features

• Two tools, one surface. remember(text) stores a piece of project memory; recall(text) retrieves the relevant pieces. Each takes a single text parameter — no kinds, states, filters, or knobs on the public API.
• Raw input is never persisted. Only controller-normalized summaries and metadata (kind, confidence, safety flags, timestamps) land in the local SQLite store.
• Project-local by default. Memory lives in .curion/ inside the project. Memories are never sent to a shared backend.
• Pluggable providers. OpenAI-compatible (default) or Anthropic. Add a fallback provider, or enable opt-in semantic retrieval.
• Stable, frozen public API. The two tools, their strict input schemas, and the public text / structuredContent surfaces are stable and frozen.
• Reproducible installs. The npm package is published with Trusted Publishing and OIDC provenance (publishConfig.provenance: true); no long-lived NPM_TOKEN secret is required.

See the full API reference for statuses, output shapes, and the clarification_needed contract.

Privacy & storage

Each project has its own .curion/ directory. Memories are stored locally and are never sent to a shared backend.

<projectRoot>/.curion/
  curion.sqlite            # SQLite database (gitignored)
  trace.sqlite             # Local trace database (gitignored, opt-out via env)
  transformers-cache/      # Embedder cache when semantic retrieval is on
  config.json              # Project config (e.g. { isPrivate: true })

When semantic retrieval is enabled, Curion may semantically search external non-private projects alongside the local project. Private projects are never surfaced. Mark a project private with .curion/config.json:

{ "version": 1, "isPrivate": true }

See Privacy & storage for the full story, including the security model, trace redaction, and .curion/config.json semantics.

Configuration essentials

Curion is configured entirely through environment variables passed by the parent process. It does not load .env files.

The minimum is a primary provider (CURION_PRIMARY_API_KEY, CURION_PRIMARY_BASE_URL, CURION_PRIMARY_MODEL, optionally CURION_PRIMARY_API_FORMAT). Optional knobs cover a fallback provider, semantic retrieval (CURION_SEMANTIC_ENABLED), log level (CURION_LOG_LEVEL), and trace enable/disable (CURION_TRACE_ENABLED).

See Configuration for the full variable list and examples.

Troubleshooting

Curion started but the agent can't see the tools. The MCP host is the process boundary. Make sure the spawn succeeded (look at stderr) and that the host's tool list refresh picked up the new server. With Claude Code, run claude mcp list to confirm curion is registered.

"No relevant memory found." but you know you stored something. The controller only stores controller-normalized summaries, not raw input. If your remember call was rejected (e.g. safety filter), no row was written. With CURION_LOG_LEVEL=debug, the recall-side retrieval logs the candidate set, scores, and threshold decisions.

Tool returns provider_error. The provider call failed. Check the reason field on structuredContent, confirm the env vars are present in the spawn environment (Curion does not load .env files), and check the provider's own status page.

Inspect the JSON-RPC stream. The official MCP Inspector is the canonical tool for ad-hoc debugging — it spawns the stdio server, lets you list tools, and lets you invoke remember / recall with arbitrary text:

npx -y @modelcontextprotocol/inspector curion

Anything written to stdout corrupts the protocol. All logging travels on stderr (see Configuration → Logging). If you wrap or redirect curion, never redirect or capture stdout — redirect stderr instead. A single stray console.log from a wrapper will break every subsequent JSON-RPC frame.

Windows / npx -y gotchas. If your MCP client does not resolve a binary on PATH (common on Windows), use the cmd /c npx wrapper described in MCP client setup → Windows / npx wrapper. For project-local installs without a global curion on PATH, prefer the absolute path to node_modules/.bin/curion rather than relying on shell resolution — see the same page.

Documentation

• MCP client setup — Claude Code, Codex CLI, OpenCode, Claude Desktop, Pi caveat, generic stdio, Windows npx wrapper, absolute-path guidance.
• Configuration — primary/fallback provider env vars, semantic retrieval, logging, trace toggle.
• API reference — remember / recall tools, output shapes, statuses, clarification_needed.
• Privacy & storage — local store layout, cross-project semantic search, private projects, trace, security model.
• CHANGELOG — release notes (Keep a Changelog format).

Support, security, and contributing

• Bug reports and feature requests: open a GitHub issue at github.com/geanatz/curion/issues.
• Security issues: do not file a public issue — see SECURITY.md for the private reporting channel. Expected response time is 7 days.
• Contributing: see CONTRIBUTING.md for the workflow, development setup, and testing expectations. By participating, you agree to the Code of Conduct.
• License: Apache License 2.0.