# MIGRATION: MCP → pi-dense-mem extension

Replaces the `pi-mcp-adapter` proxy for dense-mem with a native Pi extension
that talks directly to dense-mem's `/mcp` JSON-RPC endpoint. No dense-mem
schema changes — same backend, same v2.6 contract.

## What this replaces

- The `dense_mem` server entry in `.pi/mcp.json`
- The `mcp` meta-tool in worker agent configs (`.pi/agents/coder.md`, etc.)
- The `mcp({ tool: "dense_mem_*", args: ... })` call shape in skills

After installation, dense-mem tools are registered as **native Pi tools** under
the `dense_mem_*` namespace, exactly as if you had defined them inline.

## Step 1 — Install

Pin to a specific version (recommended for reproducibility):

```bash
pi install npm:pi-dense-mem@0.1.1
```

Or project-local (adds to `.pi/npm/` instead of global):

```bash
pi install -l npm:pi-dense-mem@0.1.1
```

The package is also published on the public npm registry as
[`pi-dense-mem`](https://www.npmjs.com/package/pi-dense-mem), so any Pi
install flow that accepts npm sources (and direct `npm install` for
non-Pi consumers) works.

## Step 2 — Configure (optional)

Defaults are fine for the standard pi-deploy compose stack. Override via
env vars or a JSON file. **Precedence: env > file > defaults.**

### Environment variables

| Var | Default | Description |
|---|---|---|
| `PI_DENSE_MEM_URL` | `http://127.0.0.1:8080/mcp` | dense-mem MCP endpoint |
| `PI_DENSE_MEM_NAMESPACE` | `dense_mem` | Tool name prefix |
| `PI_DENSE_MEM_AUTH_HEADER` | unset | Value of the `Authorization` header (e.g. `Bearer xxx`) |
| `PI_DENSE_MEM_TIMEOUT_MS` | `30000` | Per-request HTTP timeout |
| `PI_DENSE_MEM_READY_TIMEOUT_MS` | `300000` | How long to wait for dense-mem to become reachable on session start. `0` disables wait (register tools immediately, calls will fail until server is up). |
| `PI_DENSE_MEM_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |

In `docker-compose.yml` add to the `pi` service `environment:` block:

```yaml
environment:
  PI_DENSE_MEM_URL: http://dense-mem:8080/mcp
  PI_DENSE_MEM_LOG_LEVEL: info
```

### Config file (alternative)

Drop `pi-dense-mem.config.json` either next to `.pi/` (project-local) or at
`~/.config/pi/dense-mem.json` (global):

```json
{
  "url": "http://dense-mem:8080/mcp",
  "namespace": "dense_mem",
  "timeoutMs": 30000,
  "readyTimeoutMs": 300000,
  "logLevel": "info"
}
```

## Step 3 — Skills (optional but recommended)

The old call shape continues to work via the MCP proxy, but each invocation
adds one extra hop. Replace it with a native tool call to save a turn:

**Before (still works):**
```typescript
mcp({ tool: "dense_mem_recall_memory", args: { query: "..." } })
```

**After (recommended):**
```typescript
dense_mem_recall_memory({ query: "..." })
```

Search and replace in skill Markdown files:

```bash
# one-shot rewrite across skills (review diffs before committing)
find .pi/skills -name '*.md' -exec sed -i \
  -e 's/mcp({ tool: "dense_mem_\([a-z_]*\)", args: \({[^}]*}\) })/dense_mem_\1(\2)/g' \
  {} +
```

## Step 4 — Rollback

```bash
pi remove npm:pi-dense-mem
```

No data migration. dense-mem itself is untouched.

## What this does NOT change

- `docker-compose.yml` services and `dense-mem` image
- dense-mem v2.6 contract (`remember`, `recall_memory`, `retract_evidence`,
  `correct_relationship`, `get_submission_status`, `trace_memory`,
  `export_memory_pack`)
- `.pi/AGENTS.md`, `.pi/SYSTEM.md`, `.pi/settings.json`
- Other pi packages: `pi-subagents`, `pi-memory`, `@bytesbrains/pi-telegram-bridge`,
  `ping-a-human-pi`, `@upstash/context7-pi`
- Worker agent configs (`coder`, `frontend-implementer`, `reviewer`, `qa`,
  `orchestrator`) — the `mcp` tool stays in `tools:` lists for now; it just
  becomes unused for dense-mem

## Tools registered

The extension registers only the **production** dense-mem tool set. Conditional
tools (recall feedback, dreaming) and evaluation-only tools are excluded by
design; add them by extending `src/tools/production.ts` in this repo.

| Extension name | Server name | Type |
|---|---|---|
| `dense_mem_recall_memory` | `recall_memory` | read |
| `dense_mem_remember` | `remember` | write |
| `dense_mem_get_submission_status` | `get_submission_status` | read |
| `dense_mem_retract_evidence` | `retract_evidence` | write |
| `dense_mem_correct_relationship` | `correct_relationship` | write |
| `dense_mem_trace_memory` | `trace_memory` | read |
| `dense_mem_export_memory_pack` | `export_memory_pack` | read |

Registration is dynamic: on `session_start` the extension calls
`tools/list` against the server and only registers the tools the server
exposes. If dense-mem is unreachable, the extension logs a warning, calls
`registerDeferred` (no-op stub for now), and returns without registering
anything — the session still starts, dense-mem-backed skills fail at call
time with a clear error.