Corsoul
Start free
DOCS

Documentation

Practical, step-by-step guides for running Corsoul. No theory here — just the commands that get you working.

How to install Corsoul

Give your AI agent long-term memory across conversations.

The free tier needs only Node.js 18 or newer. Three steps to connect.

Prerequisite

Confirm Node.js 18 or newer is installed:

node --version

Step 1 — Initialize

Run the setup wizard once:

npx -y corsoul setup

It asks which embedding model to use for semantic recall — pick one of:

  • Local Ollama — semantic recall stays fully on your machine.
  • OpenAI — memory text is sent to OpenAI to create vectors.
  • Another OpenAI-compatible endpoint — handled by that provider.
  • Keyword-only — no embedding model, works out of the box (no find-it-by-meaning semantic recall).

Step 2 — Connect your agent

Pick one.

Claude Code (native plugin)

/plugin marketplace add CorGGai/corsoul-plugin
/plugin install corsoul-memory@corsoul

Codex / Cursor / Cline / Claude Desktop / OpenClaw

npx -y corsoul connect codex --scope=myapp:assistant:v1

Swap codex for cursor, cline, claude-desktop, or openclaw. --scope is a fixed namespace for this agent/user — all its memory accumulates under it, so reuse the same scope for the same subject. Add --dry-run to preview which files get written first.

Step 3 — Verify and restart

npx -y corsoul doctor

Once doctor is green, restart your agent — and it starts remembering.

Confirm it actually remembers

Run one round trip inside the connected agent: ask it to "remember I prefer releases on Thursday," then ask "when do I prefer releases?"; start a new conversation and ask again — the memory is still there. The free tier returns facts and a confidence value; empty related / patterns is expected (those are licensed-engine capabilities).

A few operating musts

  • One server process per data directory (the free tier uses single-process PGLite). Give each agent its own data directory, or share one local HTTP server.
  • The free HTTP server has no authentication — it binds to 127.0.0.1 only; do not expose it to a LAN or the public internet.
  • Removing the npm package does not delete memory data; by default it lives in ~/.corsoul/db (Windows: %USERPROFILE%\.corsoul\db).

Connecting other agents

The example above uses Codex. For the full recipe for each agent — Claude Code, Cursor, Cline, Claude Desktop, OpenClaw, Hermes, remote HTTP — see the Agent integrations section on the home page.