memoryhub-cli

Command-line client for MemoryHub — centralized, governed memory for AI agents.

Install

pip install memoryhub-cli

Authentication

The CLI supports two authentication modes:

API key (recommended for non-interactive use):

# Via environment variable
export MEMORYHUB_API_KEY=mh-dev-abc123

# Or store in the credentials file (INI-style, mode 0600)
mkdir -p ~/.config/memoryhub
cat > ~/.config/memoryhub/credentials << 'EOF'
[default]
api_key = mh-dev-abc123
EOF
chmod 600 ~/.config/memoryhub/credentials

API key resolution order: MEMORYHUB_API_KEY env var > ~/.config/memoryhub/credentials (section from MEMORYHUB_CONTEXT or [default]) > ~/.config/memoryhub/api-key (legacy flat file) > api_key in config.json.

Server URL:

The CLI needs to know where the MemoryHub server is. The SessionStart hook for Claude Code also reads from this config.

# Via environment variable
export MEMORYHUB_URL=https://memoryhub.example.com/mcp/

# Or save to ~/.config/memoryhub/config.json (also set by memoryhub config init)
echo '{"url": "https://memoryhub.example.com/mcp/"}' > ~/.config/memoryhub/config.json
chmod 600 ~/.config/memoryhub/config.json

URL resolution: MEMORYHUB_URL env var > url in ~/.config/memoryhub/config.json.

OAuth (interactive setup):

memoryhub login

When both are available, API key takes precedence.

Usage

# Search for memories
memoryhub search "deployment patterns"

# List memories by creation time (no semantic search)
memoryhub list --project-id my-project --max 20

# Read a specific memory
memoryhub read <memory-id>

# Write a new memory
memoryhub write "Use Podman, not Docker" --scope user --weight 0.9

# Campaign-scoped operations (requires project enrollment)
memoryhub search "shared patterns" --project-id my-project --domain React
memoryhub write "Use vLLM for embeddings" --project-id my-project --domain ML

# Compact output for LLM context injection (content only, no metadata)
memoryhub search "project conventions" --output compact

# Set up project-level memory loading
memoryhub config init
memoryhub config regenerate

# Admin: provision and manage agents
memoryhub admin create-agent my-agent --scopes user,project
memoryhub admin list-agents
memoryhub admin rotate-secret my-agent
memoryhub admin disable-agent my-agent

The --project-id flag enables campaign-scoped memory access. When your project is enrolled in campaigns via .memoryhub.yaml, the CLI auto-loads the project identifier from config, so you can omit the flag in most cases. Use --domain to tag writes or boost domain-matching results in search.

Output formats

The --output / -o flag controls output format on most commands:

• table (default) -- Rich-formatted tables for interactive use
• json -- Machine-readable JSON envelope ({"status": "ok", "data": {...}})
• quiet -- No output (exit code only)
• compact -- Content-only text for LLM context injection, no IDs or metadata

Project configuration

memoryhub config generates a project-local .memoryhub.yaml and a companion .claude/rules/memoryhub-loading.md rule file. Both files are meant to be committed so every contributor's agent inherits the same loading policy.

memoryhub config init is an interactive wizard that asks about session shape, loading pattern, focus source, and retrieval defaults, then writes both files at the project root. If a legacy .claude/rules/memoryhub-integration.md already exists, it is backed up to .bak before the new rule file is written.

memoryhub config regenerate re-renders the rule file from .memoryhub.yaml after you hand-edit the YAML. It reads the YAML and rewrites the Markdown rule file only; it does not modify .memoryhub.yaml.

Per-developer connection params (url, auth_url, client_id, client_secret) live separately at ~/.config/memoryhub/config.json and are managed by memoryhub login. They are not stored in .memoryhub.yaml and are not committed.

Further documentation

The CLI is one surface of the memory-hub monorepo. For deeper context:

• Architecture overview — System design, deployment topology
• MCP server tool reference — The 15 tools the CLI wraps
• Agent memory ergonomics design — Full .memoryhub.yaml schema, rule file templates, and session-loading patterns
• Python SDK — if you'd rather call the tools from Python

Links

• GitHub repository
• Issue tracker
• License (Apache 2.0)