pi-memd

Project-level session memory for the pi coding agent — a single MEMD.md file per project.

Why

Every other pi memory extension either uses SQLite (unreadable outside the tool), spawns LLM calls on session shutdown (slow), or scatters memory across dozens of files. pi-memd is different:

• One file — MEMD.md at project root. Human-readable. Git-ignorable.
• Zero dependencies — No SQLite, no vector DB, no git dependency. Pure TypeScript + Node fs.
• Zero LLM calls — No consolidation step. No reflection model. All operations are deterministic file I/O.
• Fast — Read on session start, cached in memory. Tools do append-only writes.
• Smart clean — Built-in dedup, stale detection, and size management via memd_clean.
• Dynamic sections — Agents can create any section on the fly (Research, Notes, Ideas, etc.). No artificial restrictions.

MEMD.md Structure

# Project Memory

## Decisions
- 2025-05-05: Using FastAPI for the API layer — simpler than Flask for async
- 2025-05-04: Chose PostgreSQL over MongoDB — relational data model fits better

## Active Context
- Docker stack uses Cloudflare Tunnel for public access
- All services on `labnet` Docker network

## Bugs & Fixes
- 2025-05-03: Immich container OOM — increased memory limit to 4G

## Changelog
- 2025-05-05: Added health endpoint to FastAPI service

## Patterns
- Always use `labnet` Docker network for new services
- Conventional commits for all repos

Sections auto-date entries for Decisions, Bugs & Fixes, and Changelog. Active Context and Patterns are undated.

Dynamic sections: Agents can write to any section name — not just the five defaults. New sections are created automatically and preserved in order after the configured sections. Use this for ad-hoc needs like Research, Notes, Ideas, or any project-specific category.

Install

pi install npm:pi-memd

Or add to ~/.pi/agent/settings.json:

{
  "packages": ["npm:pi-memd"]
}

Or project-local in .pi/settings.json:

{
  "packages": ["npm:pi-memd"]
}

Tools

Tool	Description
memd_write	Append entries or overwrite sections in MEMD.md
memd_read	Read entire MEMD.md or a specific section
memd_search	Search entries by keyword (case-insensitive)
memd_clean	Remove duplicates and stale entries (supports dry run)

Commands

Command	Description
/memd	Show MEMD.md statistics
/memd-clean	Interactive clean with confirmation
/memd-init	Create MEMD.md and add to .gitignore

Configuration

In ~/.pi/agent/settings.json or .pi/settings.json:

{
  "memd": {
    "enabled": true,
    "maxSizeKb": 64,
    "maxAgeDays": 90,
    "sections": ["Decisions", "Active Context", "Bugs & Fixes", "Changelog", "Patterns"],
    "autoInit": true,
    "injectContext": true
  }
}

Setting	Default	Description
enabled	true	Enable/disable MEMD
maxSizeKb	64	Max MEMD.md size in KB before lightweight injection
maxAgeDays	90	Days before Changelog/Bugs entries are stale
sections	5 defaults	Initial section names in order (dynamic sections auto-added)
autoInit	true	Auto-create MEMD.md on first session
injectContext	true	Inject MEMD.md content into system prompt

How It Works

1. Session start — Reads MEMD.md, auto-creates if missing, adds to .gitignore if in git repo
2. Every agent turn — Injects MEMD.md content into system prompt as <memd> XML block
3. Agent writes — Uses memd_write tool to append entries when the user says "remember this" or the agent identifies something worth persisting
4. Clean — Periodically run memd_clean or /memd-clean to remove duplicates and stale entries

vs Other Memory Extensions

Feature	pi-memd	@samfp/pi-memory	pi-self-learning	jo-inc/pi-mem
Storage	Single MEMD.md	SQLite DB	Multi .md + git	Multi .md files
Per-project	Yes	Global or project	Project-local	Global
LLM calls	None	Yes (consolidation)	Yes (reflection)	Yes (dashboard)
Human-readable	Yes	No (DB)	Yes	Yes
Size management	Built-in clean	Manual	Manual	Manual
.gitignore auto	Yes	N/A	No	No
Zero-dep	Yes (fs only)	better-sqlite3	None	None

License

MIT