Kagura Memory Cloud

View saved version →

---
name: kagura-memory
description: Use Kagura Memory Cloud from ChatGPT or Codex for long-term project memory. Trigger when the user asks to start or restore a session, recall past decisions or bug fixes, save session knowledge, remember a decision or troubleshooting note, review a context for outdated memories (maintain), inspect memory contexts, verify the kagura-memory MCP connection, or log in to it again (a Kagura tool failing with invalid_token or insufficient_scope, a new machine or workspace).
---

# Kagura Memory

Use the Kagura Memory Cloud MCP tools as the agent's persistent project memory. Local git state and files remain the source of truth for current code; memory is supplemental context for decisions, rationale, and reusable lessons.

## Tool Availability

Use the available Kagura Memory MCP namespace, typically exposed as tools such as:

- `list_contexts`
- `get_context_info`
- `recall`
- `reference`
- `remember`
- `update_memory`
- `forget`
- context, edge, sleep, and usage tools when exposed
- `explore`, which is not listed by default: `?add_tools=explore` or `?profile=full` on the MCP URL lists it

If the Kagura Memory Cloud tools are not available, the plugin's MCP server is not connected or the sign-in has expired: ask the user to reconnect the Kagura Memory Cloud plugin (it signs in with OAuth) and retry. The default tool list is the core set; `describe_tools` names the rest from inside a session.

Never print API keys or bearer tokens. When showing config, redact secrets.

## Login

When a Kagura tool fails with `401` / `invalid_token` or `403` / `insufficient_scope`, or after a move to a new machine or workspace, the connection has to be signed in again.

Never print, ask for or store a token, an API key, a device-flow code or an OAuth redirect URL. Every sign-in runs in the user's own client, not through you.

1. **Detect.** A `404` / `405`, a `5xx` or an unreachable server is not a sign-in problem: see "Tool Availability" above. A `401` / `403` is.
2. **Re-authenticate.** Tell the user how, for the client they are in:
   - ChatGPT: open the Kagura Memory Cloud plugin's settings, disconnect and reconnect it, and complete the OAuth sign-in in the browser.
   - Codex: run `codex mcp login kagura-memory` in a terminal (it opens the browser and waits for the callback), then restart Codex.
3. **After `insufficient_scope`.** Request exactly the challenge's `scope` (`WWW-Authenticate: Bearer error="insufficient_scope", scope="…"`): the scopes the token already has plus the missing one, never only the missing one. In Codex: `codex mcp login kagura-memory --scopes <scopes>`, comma-separated (`scope="memory:read memory:write offline_access"` becomes `--scopes memory:read,memory:write,offline_access`). In ChatGPT, reconnecting requests the plugin's full scope set.
4. **Verify.** Make one read call, `list_contexts()`, and report the contexts it lists and the workspace (the `/mcp/w/<workspace-id>` in the URL, else the account's current workspace). It proves the connection, not the scope: a write tool that still answers `403` / `insufficient_scope` means step 3 is still open.

## Resolve Context

Start by calling `list_contexts()` when the context is unknown. It returns a slim name→id directory (`id`, `name`, `is_private`, `is_locked`, `last_used_at` — no summaries), most recently used first, 100 per page (when `has_more` is true, pass `next_cursor` as `cursor`). If you already know the context name, narrow it with `list_contexts(name_contains="...")`; if you already resolved the id earlier in this session, reuse it instead of listing again.

Pick the context whose `name` or recent usage matches the current repository or task. When names alone don't settle it, add `include_summary=true` to a narrowed list for 300-character previews. If several contexts are plausible and the choice affects writes, ask the user.

After choosing a context, call `get_context_info(context_id=..., include_details=true)` once per session

Preview of the first 4,000 characters. Read full instructions →