@velua-ai/memory-mcp

Shared memory & TODO for your AI agents. Connect any MCP-compatible agent (Claude Code, Cursor, Codex, and more) to a single, shared per-project TODO list and knowledge base — so every agent, and every teammate, works from the same plan and the same context.

Stop re-explaining the project to each new agent. One shared memory. One shared backlog. Always in sync.

Why

• One source of truth — every agent reads and writes the same TODO and memory for the project, instead of each keeping its own scratchpad.
• Team-aware — memory is scoped to your organization, so your whole team's agents collaborate on the same board.
• Frictionless sign-in — no tokens to copy. The agent asks you to approve once in the browser, and you're in.
• Works everywhere — any MCP client. Same tools, same data, wherever you code.

Install

npm install -g @velua-ai/memory-mcp

Sign in (one click)

The first time an agent needs it, it calls the velua_login tool — a browser tab opens, you approve once, done. Your session is saved locally in ~/.velua/mcp.json. No token copy-paste.

For CI/headless use, set VELUA_TOKEN with a token issued from your Velua account.

Add it to your agent

Each agent registers MCP servers a little differently — pick yours.

Claude Code — one command, no file editing:

claude mcp add velua-memory -s user -- npx -y @velua-ai/memory-mcp

Cursor (~/.cursor/mcp.json for all projects, or .cursor/mcp.json in a repo):

{
  "mcpServers": {
    "velua-memory": { "command": "npx", "args": ["-y", "@velua-ai/memory-mcp"] }
  }
}

Codex CLI — TOML, not JSON (~/.codex/config.toml):

[mcp_servers.velua-memory]
command = "npx"
args = ["-y", "@velua-ai/memory-mcp"]

VS Code (.vscode/mcp.json) — note the top-level key is servers, not mcpServers:

{
  "servers": {
    "velua-memory": { "command": "npx", "args": ["-y", "@velua-ai/memory-mcp"] }
  }
}

Using npx means you never run a separate install step — it fetches and caches the package on first launch. Prefer a fixed binary? npm install -g @velua-ai/memory-mcp and use "command": "velua-memory-mcp" instead.

How projects are identified

Each TODO/memory board is scoped to a project. The project is resolved, in order:

1. VELUA_PROJECT if set — an explicit override.
2. A .velua.json file in the folder (or any parent) — see below.
3. Otherwise your git remote name (e.g. github.com/acme/checkout → checkout).
4. Otherwise the current folder name.

Because it keys off the git remote, two clones of the same repo — on different machines or paths — map to the same shared board, so your whole team lands in sync automatically.

No git? Drop a .velua.json in the folder

When a folder isn't a git repo (or you just want to pin the name), create a .velua.json in it — the server searches up from the working directory, like git:

{
  "project": "cliente-acme",
  "agent": "cursor"
}

All fields optional: project (the board name), agent (label for who created each item), apiUrl (advanced). An .velua.example.json is included to copy.

Options (all optional)

| Env | Default | What it does | |---|---|---| | VELUA_PROJECT | your git repo name (or folder) | which project the TODO/memory belongs to | | VELUA_TOKEN | — | a ready token, skips the browser sign-in | | VELUA_AGENT | mcp | a label for who created each item |

Tools

• velua_login — sign this device in (opens the browser).
• todo_list / todo_add / todo_update — the project's shared TODO list.
• memory_get / memory_set — the project's shared memory (key → content).

Structured memory (facts)

• memory_context — the full context bundle (committed facts + section summaries) — inject at session start.
• memory_search — search facts by text and category.
• memory_fact_add / memory_fact_update / memory_fact_delete — CRUD on structured facts (category, confidence 0-100, signals).
• memory_facts_list — list facts with category/status filters.
• memory_summary_set — upsert a section summary (user.workContext, history.recentMonths, …).
• memory_audit — read the append-only audit ledger of memory events.

Part of the Velua platform. Learn more at velua.ai.

Licensed under Apache-2.0.