pi-agent-config/scenarios/memo-inbox

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:

git pull --rebase origin main
git push origin main

See the repository 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:

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

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:

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