warp-memory-mcp
# Warp Memory MCP Server
Read-only access to **local** Warp / Oz data so other agents (Grok, Claude, etc.)
can coordinate with Warp’s AI.
Warp’s official **Agent Memory** lives on Oz (cloud, research preview, no public
API yet). This server does **not** talk to that API. It reads what Warp stores
on this Mac and a small sidecar used for Grok ↔ Oz handoffs.
## What is available locally
| Source | In `warp.sqlite` | Notes |
|---|---|---|
| Saved memories (AIFACT) | `generic_string_objects` | “Remember this” items Oz wrote locally |
| Notebooks / plans | `notebooks` | Full Warp Drive plan text |
| Conversations | `agent_conversations` | Title, first prompt, artifacts — **not** the transcript |
| User prompts | `ai_queries` | The text you typed to Oz |
| Project rules | `project_rules` | Paths to `AGENTS.md` / `WARP.md` |
| Oz cloud Agent Memory | — | Not accessible |
| Full chat transcripts | — | Cloud-only when Cloud Conversation Storage is on |
## Prerequisites
[uv](https://docs.astral.sh/uv/) is enough. No Full Disk Access is required —
the Warp DB lives in a Group Container, not `~/Library/Messages`.
If Warp is running, the DB is opened read-only with a busy timeout.
## Running
```bash
uv run --project /Users/rlittle/Development/warp-memory-mcp \
/Users/rlittle/Development/warp-memory-mcp/server.py
```
Override the database path with `WARP_SQLITE` if needed.
## Client config
Registered in:
- `~/.grok/config.toml` as `warp-memory` (Grok)
- `~/.warp/.mcp.json` as `warp-memory` (Oz can read Grok handoffs)
Restart Grok after adding the server so the tools appear.
## Tools
| Tool | Description |
|---|---|
| `status` | What is readable vs cloud-only, plus counts |
| `list_memories` / `get_memory` | Saved Warp AIFACT memories |
| `list_notebooks` / `get_notebook` | Warp Drive notebooks / plans |
| `list_conversations` / `get_conversation` | Session summaries + linked plans + prompts |
| `list_queries` | Recent user prompts to Oz |
| `search` | One search across memories, notebooks, conversations, prompts |
| `list_project_rules` | Warp project rule files |
| `write_handoff` / `list_handoffs` / `get_handoff` | Sidecar notes between Grok and Oz |
Handoffs are JSON files under `~/.warp/agent-coordination/handoffs/`. They are
**not** written into `warp.sqlite`, so they will not fight Warp Drive sync.
## Typical questions this answers
```
What did Oz prepare to work on tonight?
Search Warp notebooks for scan_processing.
Show the latest Oz conversation and its user prompts.
Write a handoff to Oz that Grok will do ScanImporter locking on 3.4beta.
```
## Safety
- Warp’s database is **read-only**.
- Command history (`commands` table) is not exposed.
- `agent_tasks` protobuf blobs are not exposed.
TDQS
Scored across 13 tools
Each tool targets a distinct resource/action: status and search serve as meta/cross-cutting entry points, list_/get_ pairs cleanly separate memories, notebooks, conversations, and handoffs, and write_handoff is clearly the only write operation. Any conceptual overlap, such as search versus list_queries, is mitigated by clear descriptions.
Most tools follow a consistent list_<plural> / get_<singular> pattern, with write_handoff fitting the verb_noun convention. The exceptions are the bare commands status and search, which would be more consistent as get_status and search_warp, but the overall pattern remains readable and predictable.
Thirteen tools is well within the ideal scope and each tool has a clear role: four list/get resource pairs, a cross-resource search, a status overview, project rule listing, and a handoff write/list/get set. No tool feels redundant or superfluous.
The server provides strong read coverage for memories, notebooks, conversations, and recent prompts, plus a complete handoff write/list/get workflow. Minor gaps exist, such as project rules being listed only as paths without a content-read tool, but the core coordination and lookup workflows are well covered.