RecallX

RecallX is a local-first personal knowledge layer for humans and agents.

It gives your local API, CLI, MCP-capable tools, and source-run UI one durable workspace for shared memory instead of scattering context across prompts, notes, and tool-specific state.

What It Is For

RecallX is built to keep these things in one local workspace:

• notes
• projects
• ideas
• questions
• decisions
• references
• activities
• relationships between them

The core idea is simple: one brain, many tools.

Why RecallX

• local-first storage with SQLite-backed workspaces
• shared memory for humans and coding agents
• append-first writes with explicit provenance
• compact context assembly for agent workflows
• HTTP API, CLI, MCP, and source-run UI access over the same local data

Distribution Paths

RecallX is documented around three public ways to use it:

1. Git public repo for direct source execution
2. npm package recallx for the full local runtime
3. npm package recallx-headless for the headless runtime

RecallX does not currently ship separate OS-native installers or package formats such as .dmg, .msi, .deb, or AppImage.

1. Git Public Repo

Use the public repo when you want the full source-run surface:

• local API under /api/v1
• source-run renderer workflow through npm run dev
• stdio MCP bridge through npm run dev:mcp during source development
• runtime workspace create/open switching without restarting the service

git clone https://github.com/jazpiper/RecallX.git RecallX
cd RecallX
npm install
npm run dev

MCP from source:

npm run dev:mcp

If you want to run the built MCP entrypoint instead, build the server first:

npm run build:server
npm run mcp

Server only:

npm run build:server
npm start

Checks:

npm run branch:check
npm run version:check
npm run check
npm test
npm run build

Start unrelated work in a separate branch/worktree instead of stacking it on the current checkout:

npm run branch:new -- fix-short-name

When you are preparing a release, bump from the highest known version instead of whatever the current branch happens to say:

npm run version:bump -- patch

Workspace lifecycle and backup commands from the same source checkout:

recallx workspace current
recallx workspace backups
recallx workspace backup --label "before-upgrade"
recallx workspace export --format markdown
recallx workspace restore --backup <id> --root /path/to/restore

The renderer Workspace page exposes the same backup, export, restore, and single-writer safety warnings over the local API.

If you want an installable runtime instead of source-run workflows, use one of the npm distribution paths below.

2. npm Full Runtime (recallx)

Use the full npm package when you want a local install that includes the API, renderer, CLI, and MCP entrypoint:

npm install -g recallx
recallx serve

In another shell:

recallx health
recallx update
recallx mcp install
recallx-mcp --help

The full npm package includes:

• local API under /api/v1
• browser renderer served from /
• recallx
• recallx serve and subcommands
• recallx-mcp

recallx mcp install writes a stable launcher to ~/.recallx/bin/recallx-mcp, which is the recommended command path for Codex and other editor MCP configs.

Workspace backup and recovery commands are available in the packaged CLI too:

recallx workspace backups
recallx workspace backup --label "before-upgrade"
recallx workspace export --format json
recallx workspace restore --backup <id> --root /path/to/restore

If the API is running in bearer mode, set RECALLX_API_TOKEN in the MCP client environment. The launcher does not write tokens to disk.

Start the packaged runtime with:

recallx serve

Optional runtime overrides:

recallx serve --port 8787 --bind 127.0.0.1
recallx serve --workspace-root /Users/name/Documents/RecallX
recallx serve --api-token secret-token

To update an npm-installed full runtime:

recallx update
recallx update --apply

recallx update currently supports npm global installs of recallx and recallx-headless. Source checkouts should keep using their package manager directly.

3. npm Headless Runtime (recallx-headless)

Use the headless npm package when you want the local API, CLI, and MCP entrypoint without shipping the renderer bundle:

npm install -g recallx-headless
recallx serve

In another shell:

recallx health
recallx update
recallx-mcp --help

The headless npm package includes:

• local API under /api/v1
• recallx
• recallx serve and subcommands
• recallx-mcp

The headless npm package does not include:

• renderer pages

At /, the headless runtime returns a small runtime notice instead of the renderer.

To update an npm-installed headless runtime:

recallx update
recallx update --apply

Node requirements:

• npm packages: Node 22.13+
• local source development: Node 25+ is recommended because the backend uses node:sqlite

Use From Other Coding Agents

If you want another coding agent to use a running local RecallX service, start with health and bootstrap first instead of assuming the protected service index is available.

• health check: GET http://127.0.0.1:8787/api/v1/health
• bootstrap: GET http://127.0.0.1:8787/api/v1/bootstrap
• service index after auth or in optional mode: GET http://127.0.0.1:8787/api/v1
• current workspace after auth or in optional mode: GET http://127.0.0.1:8787/api/v1/workspace

Recommended instruction:

Use my running local RecallX service at http://127.0.0.1:8787/api/v1.
Start by calling GET /health and GET /bootstrap.
If authMode is bearer, include Authorization: Bearer <token> before calling GET /api/v1 or GET /workspace.
Use the returned endpoint list and request examples to search nodes and activities, inspect governance state, build context bundles, and switch workspaces.
Reuse the existing local service instead of starting a new one.

Recommended instruction for MCP-connected coding agents:

Use my RecallX MCP server as an active local memory layer during this task, not just for final write-back.
Treat the current workspace as the default scope and do not switch workspaces unless I explicitly ask.
Before making assumptions or starting meaningful work, read context first: confirm the current workspace, use recallx_search_workspace when the target is still unclear, search for an existing project node when the task is clearly project-shaped, and build a compact recallx_context_bundle once the relevant node or project is known.
Prefer compact context over repeated broad browsing.
Once a project is known, append routine work logs to that project instead of writing untargeted workspace captures.
At the end of meaningful work, write back a concise summary of what changed, what was verified, and any follow-up.

MCP result rendering note:

• RecallX MCP keeps structuredContent as the authoritative machine-readable payload.
• The mirrored text content may be a compact deterministic summary rather than a pretty-printed JSON dump.
• For the current rendering policy and compatibility guidance, see docs/mcp.md.

MCP Bridge

RecallX also ships a stdio MCP adapter for agent clients that prefer tool discovery over raw HTTP calls.

MCP tool results keep structuredContent as the authoritative machine-readable payload, while content.text is rendered as a compact deterministic summary instead of a pretty-printed JSON mirror when the payload shape is known.

npm run dev:mcp
npm run mcp
node dist/server/app/mcp/index.js --api http://127.0.0.1:8787/api/v1
recallx-mcp --api http://127.0.0.1:8787/api/v1

Use npm run dev:mcp during source development. npm run mcp runs the built entrypoint, so it expects npm run build:server to have already created dist/server/app/mcp/index.js.

For launcher paths, environment variables, and editor-specific setup, see docs/mcp.md.

Docs

• docs/README.md for the full documentation map and reading order
• app/cli/README.md for the npm headless package
• docs/concept.md for product positioning
• docs/api.md for the local HTTP and CLI contract
• docs/mcp.md for MCP bridge setup
• docs/workflows.md for common usage flows
• docs/sync-backup.md for backup, restore, and single-writer multi-device guidance
• docs/schema.md for storage and data model details

License

MIT. See LICENSE.