zekra-cli

zekra-cli

Connect any AI client to the Zekra memory system in one command.

zekra is a single, dependency-free Go binary that is both the MCP server and itsinstaller. It speaks the Model Context Protocol overstdio (a thin adapter over the Zekra REST API), and it wires that server into everyMCP host — Claude Desktop, Claude Code, Codex, Gemini CLI, Cursor — so a new user goesfrom zero to a working brain in two commands.

┌────────────┐   spawns    ┌──────────────┐   HTTPS + X-Zekra-Token   ┌──────────────┐
│ MCP client │ ──────────▶ │ zekra mcp  │ ──────────────────────────▶ │ Zekra API  │
│ (Claude…)  │  (stdio)    │ (this binary)│                             │ brains + ACL │
└────────────┘             └──────────────┘                             └──────────────┘

Install

curl -fsSL https://app.zekra.dev/install.sh | sh

or, with Go:

go install github.com/fadymondy/zekra-cli@latest   # installs `zekra`

or, with npm:

npm i -g zekra-cli

Upgrade to the latest anytime (npm / go / binary aware):

curl -fsSL https://app.zekra.dev/upgrade.sh | sh

Use it as a Claude Code plugin

This repo is also a Claude Code plugin — it bundles the Zekra MCP, memory-firstslash commands, two agents, and a skill. Install:

/plugin marketplace add fadymondy/zekra-cli
/plugin install zekra@zekra

At enable time it prompts for your Zekra token (and optional endpoint / defaultbrain) and wires the MCP automatically — no .mcp.json editing. Requires the zekrabinary on PATH (any install method above), since the plugin's MCP server is zekra mcp.

What the plugin adds

Hooks — auto push/pull

The plugin ships two hooks (backed by zekra hook …, so no jq/python needed — thebinary parses the hook JSON itself, and every hook fails open: any error → no output,never blocks you):

• Memory-first rules (SessionStart) — injects the recall→answer→retain discipline atthe start of every session, so the model reaches for the brain automatically. On bydefault; turn off with the inject_rules plugin option or ZEKRA_HOOK_RULES=0.
• Auto-recall / pull (UserPromptSubmit) — uses each prompt to recall the top matchingmemories from your default brain and injects them as context. Opt-in (it hits thebrain every prompt): enable the auto_recall plugin option or ZEKRA_HOOK_AUTORECALL=1,and set a default brain (ZEKRA_AUTORECALL_BRAIN, ZEKRA_DEFAULT_NAMESPACE, or theplugin's default-brain option). Needs a saved token (zekra auth login) or the plugin'sapi_token.

Push (writing to the brain) stays model-driven on purpose — retention should beselective and distilled, not a firehose. The injected rules tell the model to memory_retainwhat's durable; /zekra:retain and the zekra-curator agent do it explicitly.

Standalone (outside the plugin) you can wire the same hooks in your own settings.json:

{
  "hooks": {
    "SessionStart":     [{ "hooks": [{ "type": "command", "command": "zekra hook rules" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "zekra hook recall" }] }]
  }
}

One-liner that installs, logs in, and wires a client in a single shot:

ZEKRA_TOKEN=cbt_… ZEKRA_CLIENT=claude-desktop \
  sh -c "$(curl -fsSL https://app.zekra.dev/install.sh)"

Quick start

zekra auth login --token cbt_…          # save endpoint + token to ~/.zekra/config.json
zekra mcp:install claude-desktop        # wire the brain into your client — done
# restart the client; the brain tools (memory_recall, memory_retain, …) appear automatically

Get a token from an admin: zekra auth token new my-laptop (admin), or ask the brain owner.

Commands

Colon (mcp:install) and space (mcp install) forms are equivalent.

Supported clients

Installs merge into existing config (other MCP servers are preserved) and areidempotent — re-running replaces just the zekra entry.

Creating and sharing a brain

zekra brain create research --description "market + competitor notes" --token

This seeds the namespace, mints a non-admin token scoped to just that brain, grantsit read+write, and prints a ready-to-paste MCP snippet you can hand to a teammate — theypaste it into their client (or run zekra mcp:install <client> --brain research) andthey're in, with access to only that brain.

Brains are enumerated from stored memories, so brain create writes one genesis markerto make the namespace exist and be connectable.

Configuration

Resolution order (highest wins): flags → environment → ~/.zekra/config.json.

The installer bakes these into each client's env block, so the client launcheszekra mcp fully configured.

MCP tools exposed

memory_recall, memory_retain, memory_get, memory_forget, memory_edit,memory_gaps, memory_resolve_gap, brain_list, brain_details, brain_create,brain_delete, brain_grant, brain_revoke_grant, brain_create_token,brain_tokens, brain_chat, secret_list/store/reveal/delete,datasource_list/create/sync/delete — 24 tools mirroring the Zekra REST contract.

Build

go build -ldflags "-X main.version=$(git describe --tags)" -o zekra .

Zero external dependencies (stdlib only) → one static binary per platform.