corsoul

The free, public, MIT client for Corsoul — durable remember / recall (plus all-tier prospective memory) for AI agents, on a local store (PGLite by default, or any Postgres via DATABASE_URL). No license, no cloud brain, no telemetry.

Reduced schema (the paid engine layer's tables are absent) and no cloud-brain code — storage and keyword recall are fully offline. Semantic recall is opt-in: if you configure an embeddings provider, your remember/recall text is sent to THAT provider to be embedded (a local Ollama stays on your machine; a hosted provider does not). The one other thing that reaches the network is npm: by default the agent entries corsoul connect writes run this client through npx, which fetches it from the npm registry when the agent starts. No Corsoul server, no phone-home. With no provider set, recall is keyword-only and fully local.

Install

npm install corsoul        # library
npm install -g corsoul     # also installs the `corsoul` CLI / MCP server

Use as a library

import { scope } from 'corsoul'

const npc = scope('game-x:companion:aria')
await npc.remember('the guide helped me cross the river at dusk')

const ctx = await npc.recall('who helped me?')
console.log(ctx.facts)      // ['the guide helped me cross the river at dusk']
console.log(ctx.related)    // []  ← graph neighbours: paid cloud tier
console.log(ctx.patterns)   // []  ← abstract patterns: paid cloud tier

Use with an AI agent (MCP)

Installed globally, corsoul is also a free, offline MCP server. One command wires it into a client — it merges the server into the client's config and writes the capture contract, so the agent recalls/remembers on its own:

corsoul                                            # stdio (Claude Code, Codex, Cursor, Cline)
corsoul connect claude-code --scope=myapp:me:v1    # also: codex, cursor, cline, claude-desktop, openclaw

Full setup → the install guide on GitHub. Every agent, HTTP/YAML agents via one-command named profiles, corsoul contract, a supervised shared brain, shared-vs-separate topologies, and step-by-step verification live there.

On Windows, scripts/corsoul-tray.ps1 puts a status light in the notification area: it polls the local server and tells you when memory has stopped, rather than leaving you to notice later. It can start with you at sign-in (a per-user setting it writes and removes from its own menu). By default it only reports — restarting is a menu item you click; corsoul tray --auto-restart turns on automatic recovery.

Tools: corsoul_remember / corsoul_recall / corsoul_forget, the prospective-memory trio (corsoul_intend / corsoul_due / corsoul_resolve_intent), and corsoul_set_core / corsoul_get_core. There is deliberately no corsoul_sleep — graph/pattern consolidation is the paid tier, so recall always returns related: [] / patterns: [].

API

| Method | Description | |---|---| | scope(id) | An automatically-isolated memory handle. | | remember(text, { type?, metadata? }) | Store an event; immediately recallable. | | recall(query, { topK? }) | Semantic + keyword recall over Layer 1. | | forget(slug) | Soft-delete a memory (reversible). | | intend({ text, dueAt?/dueInSec?, cadence? }) | Record a prospective intention. Returns its id. | | due({ within? }) | Pure read: intentions due now (or within a window). Never fires. | | resolveIntent(id, { status }) | Close an intent (done/cancelled/expired); a recurring done reschedules. | | setCore({ identity?, values?, disposition? }) | Set the baseline self. | | getCore() | Read the current core. |

Storage + keyword recall need no LLM. Semantic recall needs an embeddings provider (LLM_BASE_URL + LLM_EMBED_MODEL, or run corsoul setup). Data dir: CORSOUL_DATA_DIR (default ~/.corsoul/db) or DATABASE_URL. The full config table and the corsoul activation scheduler are in the install guide.

Upgrading

A licensed, cloud-capable client (private delivery) adds connectCloudBrain() + scope.sleep() — graph + pattern consolidation on a cloud brain: the memory store stays on your machine, and each consolidation uploads a working set of it to that brain. Not a public npm install: see the Corsoul project or write to [email protected].

License

MIT © 2026 Corsoul