pi-memory-system: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Pi Memory System is a memory extension for Pi Coding Agent. It gives the AI assistant persistent, layered memory using Markdown files and a subagent-based distillation pipeline.

Core design: The main LLM never sees raw conversation history. Short-term memory (per-round dialogue-summary.md sections, sliding window of last 5) is injected each turn; a consolidation subagent distills every 5 rounds into long-term memory; a manually-triggered cleaner (hippocampus) maintains memory files. The main LLM exclusively maintains the notebook.

Architecture

Three-layer memory system:

1. Core Prompt (core-prompt.md) — identity, principles, thinking framework. Injected into every turn's system prompt.
2. Session Notebook (projects/<name>/notebook.md) — active tasks, todos, constraints. Maintained by subagent.
3. Long-term Memory (projects/<name>/memories/*.md + personal/*.md) — cross-session knowledge. Written by subagent via remember tool.

Turn lifecycle

before_agent_start → inject core-prompt + rules + compact index + last-5-rounds summary + notebook + related memories
context → strip all history except system + current user message
agent_end → dump messages → python3 run_extraction.py → raw-<n>.md backup + dialogue-summary append
   every 5th round (section count % 5 == 0) → spawn consolidation subagent (detached, async)
session_shutdown → if un-consolidated rounds ≥ 3 → spawn consolidation subagent (detached)
/memory-clean (manual) → spawn cleaner subagent (foreground, visible report)

Per-session short-term memory lives in turns/sessions/<id>/ (raw-.md, dialogue-summary.md, consolidation-input.md); long-term memory (memories/) and notebook are shared at project level. Notebook is maintained exclusively by the main LLM — subagents only read it.