# memo-inbox — Pi agent scenario

This directory is the **memo-inbox** Pi agent. It is tracked as part of the
`pi-agent-config` repository — it is **not** a standalone repository.

- Gitea repo: `kai/pi-agent-config` on `192.168.50.45` (web `:3000`, SSH `:222`).
- Remote: `origin -> gitea-45:kai/pi-agent-config.git`, branch `main`.
- Auth: SSH key only (`~/.ssh/id_ed25519_gitea`, Git user `git`); no HTTP token.
- Push and pull from the repository root, not from here:

```bash
git pull --rebase origin main
git push origin main
```

See the repository [`README.md`](../../README.md), section “Gitea repository and
push authentication”, for the full SSH config and caveats.

## Layout

- `profile.toml` — the launch contract; `deploy = "mirror"` records what the live service does.
- `workspace/` — the mirrored live agent configuration.
- `docs/` — scenario-specific documentation.

# Scenario: memo-inbox

Routes Kai's Telegram and WeChat messages into Google Calendar, today's Obsidian
todo list, or a journal memo — without requiring slash commands or confirmation.

Live service: `pi-memo-telegram.service` (user unit, active).
Live workspace: `/home/claw/pi-workspaces/memo-inbox`.

## Migration status

**Mirrored, not yet managed.** Migrated 2026-08-27 by copying; the live
directory was not moved or modified and the service was not restarted. All four
tracked files match production byte for byte.

| Tracked | Live target |
|---|---|
| `workspace/AGENTS.md` | `<workspace>/AGENTS.md` |
| `workspace/.pi/extensions/memo-guard.ts` | `<workspace>/.pi/extensions/memo-guard.ts` |
| `workspace/.agents/skills/pi-memo-inbox/SKILL.md` | `<workspace>/.agents/skills/pi-memo-inbox/SKILL.md` |
| `workspace/bin/journal-sync.sh` | `<workspace>/bin/journal-sync.sh` |

Verify at any time:

```bash
scripts/pi-diff.sh memo-inbox
```

## Deliberately not tracked

| Path | Why |
|---|---|
| `telegram-gateway/` | Application code (622 + 343 lines), not configuration. It also sits inside the agent's own cwd, which is a separate design problem — an agent's readable workspace should not contain the program that drives it. Relocating it is a follow-up. |
| `.ccgram-uploads/` | Runtime data: inbound Telegram voice notes, photos and documents. |
| `download.html` | Generated artefact. |
| `telegram-gateway/.venv/` | Toolchain. |
| `gateway.py.bak-20260818-wechat` | Stale backup. |

## Why this scenario matters to the others

memo-inbox is the **reference implementation** for three patterns that the
curator scenario lacks. See `docs/gateway-patterns.md` for the full comparison.

1. **Long-lived RPC process.** `gateway.py` starts `pi --mode rpc` once and
   drives it turn by turn, with protocol-correct `\n`-only JSONL framing.
2. **Session rotation.** Rotates after 24 prompts, plus a `messageCount >= 60`
   guard. pi has no session TTL and auto-compaction does not fire on a
   1.05 M-token context window, so a gateway must do this itself.
3. **Deterministic write receipts.** The reply a user sees for a state change is
   harvested from `tool_execution_end` on the mutation tools, not generated by
   the model. This is the single most valuable pattern in the repository.

Its `memo-guard.ts` is also the origin of `shared/extensions/pi-guard-base.ts`:
path containment, the restricted `read` override, `setActiveTools`, and the
`tool_call` block.

## Known gaps

Recorded here rather than fixed, because this service is in daily use and the
migration was scoped to zero behaviour change. Tracked as plan phase 5.

| Gap | Effect |
|---|---|
| No `--no-extensions` / `--no-skills` / `--no-prompt-templates` / `--no-themes` | `~/.pi/agent/extensions/{herdr-agent-state,pi-memo-trust}.ts` and `~/.agents/skills/{find-skills,modsearch,summarize}` load into this agent. `find-skills` instructs the agent to discover and install further skills. |
| No `.pi/SYSTEM.md` | Runs on pi's default coding-assistant prompt, including the block of absolute paths to pi's own docs with an instruction to read them and follow cross-references. `AGENTS.md` corrects course from on top of that rather than replacing it. |
| Full environment inherited | `ASR_API_KEY` and anything else in the unit reaches the node process and every extension it loads. |
| No `--no-builtin-tools` | Built-ins are active at startup and are narrowed only once `session_start` fires and `setActiveTools` runs. The `tool_call` hook still blocks them, so this is a defence-in-depth gap rather than an open hole. |
| `--continue` instead of `--session-id` | Continuity depends on "most recent session for this cwd". A stray interactive `pi` run in the same directory could be continued by the service. |
| `allowed-tools:` in SKILL.md | Not consumed by pi 0.84.3. Harmless, but do not treat it as enforcement. |

## Applying changes

```bash
scripts/deploy-scenario.sh memo-inbox            # dry run, shows the diff
scripts/deploy-scenario.sh memo-inbox --apply    # then restart the unit yourself
```

The deploy script never restarts a service. For this scenario:

```bash
systemctl --user restart pi-memo-telegram.service
systemctl --user status  pi-memo-telegram.service
```