su-memory

Minimal memory + skill incubator layer for Pi.

A lightweight, file-based memory extension that stays aligned with Pi's native prompt and skill system. No vector search, embeddings, RAG, or background compaction — just files.

Install

pi install su-memory

Or from a local path:

pi install /path/to/su-memory

After install, run /reload in Pi.

How it works

Three files under ~/.pi/agent/memory/:

File	Purpose	Loaded
user.md	Stable user context (identity, projects, preferences) — written by you	Every session
memory.md	AI-managed persistent memory — the model reads/writes it on-demand	Only when relevant
incubator/	Draft reusable procedures before they become Pi skills	Never auto-loaded

When the agent reads, edits, or writes the memory file using the built-in read/edit/write tools, the TUI shows a clean label (read memory, edit memory, write memory) instead of the full filesystem path.

The agent is prompted with a Memory and Procedural Knowledge Policy that defines:

• Source priority: user.md → skills → memory.md → incubator/
• When to read memory.md (only when past work is referenced, prior context is needed, or ambiguity can't be resolved from user.md)
• When to promote incubator drafts to skills (reused ≥2 times or user confirms)
• Procedures belong in Pi skills, not in memory.md

Design

• No custom tools required — three legacy tools (read_memory, edit_memory, write_memory) exist for backward compatibility, but the model is directed to use read/write/edit directly on file paths
• Clean TUI rendering — all three legacy tools use custom renderCall/renderResult to show clean one-liners (read memory, edit memory, write memory). The built-in read/edit/write tools are similarly patched: they delegate rendering to the original implementations but rewrite the path label to "memory" when the target is ~/.pi/agent/memory/memory.md
• No autonomous memory rewriting — the model suggests updates explicitly
• No hidden state — all state lives in files under ~/.pi/agent/memory/
• Deterministic — files are never silently overwritten; only created if absent

File layout

~/.pi/agent/
├── extensions/
│   └── memory/
│       └── index.ts              # Extension entry point
└── memory/
    ├── user.md                   # Your manual context (read-only to agent)
    ├── memory.md                 # AI-managed memory (on-demand)
    └── incubator/
        └── README.md             # Incubator policy

The full specification is in the package root as SPEC.md.

License

MIT