@usememra/pi-memory

Persistent memory for pi — the coding agent. Works with any LLM pi supports (Anthropic, OpenAI, Google, and more). Pick cloud (Memra) or local (memra-local) — same tools, same API, your choice.

Your agent forgets everything between sessions. Memra is the memory layer that fixes that.

Install

From a local repo checkout

pi install ./pi-extension

From npm (recommended for end users)

pi install npm:@usememra/pi-memory

Reload with /reload.

Setup

On first session start the extension auto-detects:

1. MEMRA_API_KEY in env → cloud mode.
2. A running memra-local on http://127.0.0.1:8765 → local mode.
3. Otherwise it asks you.

Cloud defaults to https://usememra.com/api and automatically talks to the public API at /v1/... and /health.

Config lives at ~/.memra/pi-extension.json (mode 0600). The only other thing ever written is the opt-in per-directory override (<workspace-root>/.memra/config.json plus a self-ignoring .memra/.gitignore) — see Per-directory override.

Environment Variables

| Variable | Description | |----------|-------------| | MEMRA_API_KEY | Cloud API key (memra_live_...) | | MEMRA_PROJECT_ID | Cloud project ID / namespace (default: default) | | MEMRA_TENANT_ID | Cloud tenant ID / namespace root (default: pi-agent) |

Commands

| Command | Action | |--|--| | /memra | Interactive hub | | /memra status | Active backend + health | | /memra switch | Pick cloud or local | | /memra namespace <name> | Set the global project/namespace (one-shot, no prompts) | | /memra namespace <name> --local | Pin a project/namespace for this directory only (one-shot) | | /memra namespace | Interactive: asks for a name, then where to save (global / this project / remove override) | | /memra tenant <id> | Set cloud tenant ID | | /memra setkey | Set cloud API key | | /memra autorecall | Toggle auto-recall on new turns | | /memra signup | Open signup page | | /memra reset | Wipe extension config |

A footer badge (☁ memra cloud · <project> or ⌂ memra local · <namespace>) shows the active backend at all times. In cloud mode it prefers the project's human-readable name when one has been resolved. The badge appends ‹.memra› while a per-directory override is active, and · DOWN when the backend health check is failing.

Per-directory override

You can pin a different project (cloud) or namespace (local) for a single repo without touching your global config:

/memra namespace my-project --local

This writes <workspace-root>/.memra/config.json:

{
  "projectId": "my-project",   // used in cloud mode
  "namespace": "my-project"    // used in local mode
}

• Location: the workspace root is the nearest ancestor of pi's working directory containing .git (falling back to the working directory itself). If that directory is your home, the override is ignored — ~/.memra is the global config dir and must never silently repoint every session launched from $HOME.
• Precedence: override file > global config. Only the project/namespace is overlaid; mode, API key, tenant, URL, and auto-recall always come from the global config (secrets are never read from the override file).
• Visibility: the badge shows ‹.memra› whenever an override is active — even when its value equals the current global one (it's still a pin) — and /memra status names the override file.
• Git: the extension also writes a .memra/.gitignore containing config.json (unless one already exists), so the override stays machine-local instead of repointing collaborators' routing via a commit. Your repo's own .gitignore is never touched.
• Removing it: run /memra namespace and pick "Remove project-local override (use global)", or /memra reset (which deletes it along with the global config).

Auto-Recall

When auto-recall is enabled (default), the extension automatically searches your memory store before each agent turn and injects relevant memories into the LLM context. This means your agent remembers across sessions without you having to ask.

Toggle with /memra autorecall.

Tools (LLM-facing)

Every tool mirrors the Memra API surface:

| Tool | Description | |------|-------------| | memra_recall | Semantic recall by natural-language query (primary read verb) | | memra_remember | Store a fact, decision, preference, or context (primary write verb) | | memra_get | Fetch a single memory by ID | | memra_list | List memories, optionally filtered by type | | memra_delete | Delete a memory permanently | | memra_supersede | Replace an outdated memory (preserves audit trail) | | memra_history | View the supersession chain for a memory | | memra_health | Check backend reachability | | memra_search | Deprecated alias of memra_recall (still callable) | | memra_add | Deprecated alias of memra_remember (still callable) |

The LLM picks tools automatically based on your conversation. The extension routes every call to the active backend (cloud or local).

Security

• API key read from MEMRA_API_KEY → ~/.memra/pi-extension.json → interactive prompt. Never logged.
• Local mode is bound to loopback (127.0.0.1 / localhost) only.
• Cloud mode refuses non-HTTPS URLs.
• Namespace / project / tenant inputs are validated before saving.
• Writes confined to ~/.memra/pi-extension.json plus — only on an explicit --local / "this project only" save — <workspace-root>/.memra/config.json and its self-ignoring .memra/.gitignore.

Cloud vs Local

| | Cloud | Local | |--|--|--| | Storage | Managed (EU, Hetzner Helsinki) | Your machine | | Sync | Multi-device | None (use cloud for sync) | | Offline | No | Yes | | Setup | API key | pip install 'memra-local>=0.3.1' && memra serve | | Price | Free tier + paid plans | Free, BUSL-1.1 (memra-local) |

Get a cloud key: usememra.com/install

Recommended config for Memra Cloud

For shared persistent memory across pi sessions, set:

export MEMRA_API_KEY="memra_live_..."
export MEMRA_PROJECT_ID="memra-brain"
export MEMRA_TENANT_ID="pi-agent"

Then run pi and /reload.

License

MIT. Use it anywhere. The Memra backend (usememra.com) and memra-local server have their own licenses.