memory

memory plugin

Slash commands + auto-capture hooks bridging Claude Code to the AstraMemory service. Wraps the existing MCP server with one-keystroke recall/store and durable session capture across compaction.

What's in it

Slash commands

• /recall <query> — searches AstraMemory for memories matching the query and injects the top results into context. Uses the AstraMemory MCP search_memory tool. Honors inline filters like "in loop" / "for crew" → project_id, "handoffs" / "cost-reports" → tags.
• /remember <text> — stores the supplied text as a memory in AstraMemory with metadata inferred from context (project = repo name, tags = topical keywords, type = note / decision / fact based on phrasing).

Hooks

• PreCompact / SessionEnd / SubagentStop — hooks/scripts/*.sh capture the tail of the current transcript and POST it to the AstraMemory server at ${MEMORY_API_URL}/ingest/transcript. The server scrubs secrets, stores the raw turns as a summary memory, and runs an LLM extractor that emits typed atoms (decision, fact, lesson, event) linked to prior memories via the graph. Server-side ingest extraction lands in a follow-up release; until then the endpoint stores the raw digest and the typed-atom + graph-edge pipeline is pending.

  Hooks always exit 0 — they never block compaction or session shutdown. Failures (no Bearer cache, server down, jq missing) are silent. POSTs make MEMORY_INGEST_RETRIES total attempts (default 2) before giving up on 5xx; 4xx is final.

  Hook	Max turns	Env override
  PreCompact	20	MEMORY_PRECOMPACT_MAX_TURNS
  SessionEnd	40	MEMORY_SESSION_MAX_TURNS
  SubagentStop	12	MEMORY_SUBAGENT_MAX_TURNS

MCP server registration

.mcp.json declares the memory MCP server with type: http. The URL is resolved from ${MEMORY_MCP_URL} at Claude Code launch — see the Profiles section below for how that gets set.

The Authorization header is Bearer ${MEMORY_BEARER}. MEMORY_BEARER is a JWT minted by memory-login (one-time) and refreshed by memory-refresh.

.mcp.json reads MEMORY_BEARER from your OS environment at Claude Code launch — it is NOT auto-populated. Export it from your shell rc:

export MEMORY_BEARER="$(memory-refresh)"

The MCP transport binds the token at Claude Code launch — long sessions can outlast the ~1h TTL; restart Claude Code or re-run memory-refresh then restart if the MCP server starts returning 401.

Cached tokens live at ~/.config/memory/auth.json (POSIX) or %APPDATA%\memory\auth.json (Windows). Move or delete the file to force a fresh memory-login.

Pair a workstation (device-flow)

From v0.4.0 you can pair a workstation to an AstraMemory environment without copying API keys through clipboard or env vars.

Steps:

1. In the AstraMemory dashboard click "Connect this machine" — this mints a short-lived claim code (ABCD-1234) and opens a status panel.

2. Run the CLI in the repo you want to pair:

   # In the dashboard: click "Connect this machine" → copy code
   memory-connect ABCD-1234 --env prod
   

3. The dashboard status panel flips to ✓ first event received within seconds.

Options:

memory-connect <code> [--env <env>] [--url <override>] [--workspace <name>]

  --env <env>         Environment to target. Resolution order:
                        --env flag > $ASTRAMEMORY_ENV > "prod"
  --url <url>         Override the API URL directly (skips profiles.json lookup).
  --workspace <name>  Workspace identifier written into the token file.
                      Default: basename of the current working directory.

Exit codes: 0 success · 1 code expired/invalid · 2 network failure · 3 filesystem write failure · 4 profile not found.

~/.astramemory/profiles.json

Seed this file once per machine. Each key is an env name:

{ "prod":  { "apiUrl": "https://api.astramemory.com" },
  "local": { "apiUrl": "http://localhost:5201" } }

memory-connect reads profiles.json[env].apiUrl unless --url is passed.

~/.astramemory/tokens.<env>.json

Written (atomically, preserving existing entries) after a successful redeem. Read by the FEAT-280 plugin hooks to resolve apiKey per workspace:

{
  "my-repo": {
    "apiKey": "sk-...",
    "label": "claim-20260622120000",
    "tenantId": "tenant-abc123",
    "repoPath": "/home/user/work/my-repo",
    "pairedAt": "2026-06-22T12:00:00.000Z"
  }
}

Each key is the workspaceId (defaults to basename(cwd)). Multiple workspaces per env are supported — pairing a second repo appends a new key without touching existing entries.

---

Profiles

The plugin ships two committed profiles. Pick one by setting MEMORY_ENV in your shell before launching Claude Code.