pi-memory — Persistent Memory

A file-based memory system that persists knowledge across sessions using plain Markdown.

Architecture

code

<base-path>/
├── MEMORY.md              # Long-term curated memory (facts, preferences, decisions)
└── memory/
    ├── 2026-02-11.md      # Daily log — append-only session notes
    ├── 2026-02-10.md
    └── ...

•MEMORY.md — The "brain". Organized into ## Sections. Survives compaction. Editable in place.
•memory/YYYY-MM-DD.md — Daily append-only logs. Timestamped entries. One file per day.

The base path defaults to cwd. Override with settings.json:

json

{ "pi-memory": { "path": "/path/to/memory/dir" } }

Tools

memory_read

Read memory contents.

target	description
`long_term`	Read full MEMORY.md
`daily`	Read a specific date's log (default: today). Pass `date: "YYYY-MM-DD"` for other dates.
`list`	List all available daily log files

memory_write

Write to memory.

target	description
`daily`	Append a timestamped entry to today's log. Used for session notes, progress, decisions.
`long_term`	Update MEMORY.md. Pass `section` to replace a specific `## Section`, or omit to append.

Long-term memory sections — use section parameter to target:

code

memory_write target=long_term section="Preferences" content="- Prefers dark theme\n- Terminal-first tools"

This replaces the content under ## Preferences. If the section doesn't exist, it's created.

Daily log entries — auto-timestamped:

code

memory_write target=daily content="Completed the auth refactor. Using JWT with RS256."

Creates ### HH:MM entry in today's file.

memory_search

Full-text search across MEMORY.md and all daily logs.

code

memory_search query="JWT" limit=10

Returns matching lines with ±1 line of context, grouped by file.

When to Write Memory

Always write to long-term memory when:

•User explicitly says "remember this", "save this", "note that..."
•You learn a new preference, convention, or decision
•A significant architectural or design choice is made
•You discover something about the user's workflow or environment

Always write to daily log when:

•Starting or completing significant work
•Making key decisions during a task
•Encountering and resolving blockers
•At the end of a work session (summarize what was done + next steps)

Section organization for MEMORY.md

Keep MEMORY.md well-organized with clear sections:

markdown

# Long-Term Memory

## About [User]
- Key facts, role, location, interests

## Preferences
- Communication style, tool preferences, conventions

## Active Focus
- Current projects and priorities (update as they shift)

## Decisions & Conventions
- Coding conventions, workflow rules, architectural decisions

## People & Relationships
- Key contacts and collaborators

## Recurring Patterns
- Things frequently asked about or worked on

Memory Hygiene

Periodically review and clean up memory:

•Deduplicate — Check for repeated sections in MEMORY.md (use memory_read target=long_term)
•Archive stale info — Remove outdated decisions or completed project references
•Consolidate daily logs — Important patterns from daily logs should be promoted to MEMORY.md
•Keep sections focused — Each ## Section should have a clear purpose

System Prompt Injection

At each agent turn, the extension automatically injects into the system prompt:

•Full MEMORY.md content
•Yesterday's daily log (if exists)
•Today's daily log (if exists)

This means the agent always has recent context without needing to call memory_read.