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