su-memory

A file-based memory repository for Pi.

A general, skill-like abstraction for durable context. Memory is organized the same way Pi skills are — markdown files with progressive disclosure — but holds knowledge and context rather than procedures.

• No vector search, embeddings, RAG, or background compaction. Just files.
• No custom tools. The model uses the built-in read/edit/write/bash tools directly on the repository.
• No skills inside memory. Reusable procedures stay in Pi's native skill system.

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

The repository lives at ~/.pi/agent/memory/ and is its own git repo:

~/.pi/agent/memory/
├── SOUL.md                 # human-authored identity/values (never auto-edited)
├── memory.md              # global entry point (< 2000 tokens)
├── preferences/
│   ├── index.md            # one-line index per file
│   └── *.md                # loaded on demand
├── projects/
│   ├── index.md
│   └── *.md
├── knowledge/
│   ├── index.md
│   └── *.md
└── archive/                # obsolete material, not loaded

Progressive disclosure

Only these are injected into the system prompt (the "always-on" set):

• SOUL.md
• memory.md
• preferences/index.md, projects/index.md, knowledge/index.md

Everything else is loaded on demand by the model with read. The model never receives the whole repository. The always-on set is kept small by rule and by soft caps (files past their cap are injected truncated with a marker).

What goes where

Category	Holds
preferences/	Stable info about how the user/agent operate
projects/	Current or recurring work (goal, architecture, decisions, state)
knowledge/	General reusable technical/domain knowledge
archive/	Obsolete files moved out of active context

Reusable procedures and workflows belong in Pi skills, not memory.

Writing memory

The model writes memory only when future work will likely become easier because it exists — solved hard problems, repeated user preferences, project decisions. It does not store conversation summaries, logs, or transient thoughts. The repository is git-versioned; the model commits with descriptive messages and uses git diff/log/revert to manage history.

Commands

• /memory — show the repository tree, git status, and recent commits.
• /memory commit <msg> — stage and commit all changes.
• /memory log — show recent commits.

Design

• Minimal prompt — only SOUL.md + memory.md + three indexes + a short policy are injected; the rest is lazy-loaded.
• Agent editable — the model manages its own knowledge with the built-in file tools.
• Versioned — the repository is a git repo; changes are reversible.
• Human authored SOUL — SOUL.md is never modified automatically.
• No hidden state — everything lives in plain files under ~/.pi/agent/memory/.

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

License

MIT