pi-memory-md

Letta-like memory management for pi using git-backed markdown files.

Features

• Persistent Memory: Store context, preferences, and knowledge across sessions
• Git-backed: Version control with full history
• Prompt append: Memory index automatically appended to conversation at session start
• On-demand access: LLM reads full content via tools when needed
• Multi-project: Separate memory spaces per project

Quick Start

# 1. Install
pi install npm:pi-memory-md
# Or for latest from GitHub:
pi install git:github.com/VandeeFeng/pi-memory-md

# 2. Create a git repository (private recommended)

# 3. Configure pi
# Add to ~/.pi/agent/settings.json:
{
  "pi-memory-md": {
    "memoryDir": {
      "repoUrl": "git@github.com:username/repo.git", // Or HTTPS format
      "localPath": "~/.pi/memory-md",
      "globalMemory": "global" // optional, global as default
    }
  }
}

# 4. Start a new pi session
# type /skill:memory-init slash command to initialize the memory files

Security recommendation

Configure pi-memory-md in global settings (~/.pi/agent/settings.json) instead of project settings (.pi/settings.json).

If project settings could override these options, a repository could redirect your memory to another local path, point sync at a different remote repo, or enable automatic pull/push behavior you did not intend.

For this reason, project-level .pi/settings.json does not override these pi-memory-md options: repoUrl, localPath, memoryDir, sync hooks, and tape.tapePath.

How It Works

Session Start
    ↓
1. Git pull (sync latest changes)
    ↓
2. Scan all .md files in memory directory
    ↓
3. Build index (descriptions + tags only - NOT full content)
    ↓
4. Deliver memory index via `message-append` or `system-prompt`
    ↓
5. LLM reads full file content when needed

Usage Examples

Simply talk to pi - the LLM will automatically use memory tools/skiils when appropriate:

You: Save my preference for 2-space indentation in TypeScript files to memory.

Pi: [Creates or updates a memory markdown file with the standard file tools]

You can also explicitly request operations:

You: List all memory files for this project.
You: Search memory for "typescript" preferences.
You: Read core/USER.md
You: Sync my changes to the repository.

The LLM automatically:

• Reads memory index at session start (appended to conversation)
• Creates or updates memory markdown files when you ask to remember something
• Syncs changes when needed

Available Capabilities

Slash Commands In Pi

You can also use these slash commands directly in pi:

• /memory-refresh: Refresh memory context from files (rebuild cache and deliver into current session)
• /memory-check [max-lines]: Check memory repository status (project name, git status, path) and folder structure (tree output defaults to 25 lines)

Built-in Tools & SKILLs

The LLM can use these tools and skills to interact with memory:

Memory Management Tools

Tool	Parameters	Description
memory_sync	{action: "pull" / "push" / "status"}	Git operations
memory_list	{directory?: string}	List project memory by relative path; global paths stay absolute
memory_search	{query?, grep?, rg?}	Search by tags/description and custom grep/ripgrep patterns
memory_check	{}	Check current project memory folder structure

Memory SKILLs

Skill	Description
memory-init	Initialize the memory repository, clone/sync git, and create the basic directory structure
memory-import	Curate durable memory from URLs, folders, or files after confirming what should be preserved
memory-write	Create or update memory markdown files with valid frontmatter using native file tools

User can easily extend their own workflows with these skills. Although this sacrifices some stability, it improves flexibility and user autonomy. This is a deliberate tradeoff after my careful consideration.

Memory Delivery Modes

The extension supports two base modes for delivering memory into the conversation. When tape mode is disabled, behavior is exactly as described below. When tape mode is enabled, the same delivery mode still applies, but tape changes how memory files are selected.

1. Message Append (Default)

{
  "pi-memory-md": {
    ...
    "delivery": "message-append"
  }
}

• Memory is sent as a custom message delivered only once per session (on first agent turn)
• Not visible in the TUI (display: false in pi-tui) This hidden message is delivered in the same agent turn, so it does not create a second LLM request; it only adds tokens to the current request
• Persists in the session history
• Pros: Lower token usage, memory persists naturally in conversation
• Cons: Only visible when the model scrolls back to earlier messages

2. System Prompt

{
  "pi-memory-md": {
    ...
    "delivery": "system-prompt"
  }
}

• Memory is appended to the system prompt delivered on every agent turn
• Pros: Memory always present in system context
• Cons: Higher token usage (repeated on every prompt)

Hooks

• sessionStart: ["pull"]: sync from upstream, fresh fetch/pull evidence within 12 hours skips another fetch. This avoids repeated network checks on every new session while still refreshing upstream periodically.
• sessionEnd: ["push"]: commit and push memory when the session ends.

More trigger actions will be added later, even custom hooks.

Full Configuration

{
  "pi-memory-md": {
    // "enabled": false,

    "memoryDir":{
    // git remote url
    "repoUrl": "git@github.com:username/repo.git", // Or HTTPS format

    // Root dir for all memory (cloned from repo) `~/.pi/memory-md` as default
    "localPath": "~/.pi/memory-md",

    // Shared memory folder name under localPath.
    // Only enabled when explicitly configured
    // "global" -> {localPath}/global, "foo/bar" -> {localPath}/bar.
    // "" or omitted -> disabled, "   " -> {localPath}/global, ".." -> {localPath}/global.
    "globalMemory": "global"
    },

    // `injection` is still accepted as a legacy alias for `delivery`.
    "delivery": "message-append",
    "hooks": {
      "sessionStart": ["pull"],
      "sessionEnd": ["push"]
    }
  }
}

Setting	Default	Description
enabled	true	Enable extension
memoryDir.repoUrl	Required	Git repository URL
memoryDir.localPath	~/.pi/memory-md	Local memory clone path
memoryDir.globalMemory	disabled	Shared memory folder name (relative to localPath), enabled only when explicitly configured
delivery	"message-append"	Memory delivery mode: "message-append", "system-prompt"
hooks.sessionStart	["pull"]	Actions to run when a session starts, pull syncs from upstream and skips another fetch when FETCH_HEAD is fresh within 12 hours
hooks.sessionEnd	[]	Actions to run when a session ends
tape.enabled	false	Enable tape mode for dynamic context selection

When settings change, run /reload to apply them.

Legacy config is still supported:

{
  "autoSync": {
    "onSessionStart": true
  }
}

{
  "localPath": "~/.pi/memory-md",
  "repoUrl": "git@github.com:username/repo.git", // Or HTTPS format
}

Memory File Format

---
description: "User identity and background"
tags: ["user", "identity"]
created: "2026-02-14"
updated: "2026-02-14"
---

Markdown content...

Directory Structure

~/.pi/memory-md/
├── global/                 # Optional shared memory when globalMemory is enabled
│   ├── USER.md             # Optional shared user profile and preferences
│   ├── MEMORY.md           # Optional shared durable notes, conventions, and lessons learned
│   └── TASK.md             # Optional shared task template
└── project-name/           # git rev-parse --show-toplevel
    ├── core/
    │   ├── USER.md         # Optional project user profile and preferences
    │   ├── TASK.md         # Optional project task template
    │   └── project/        # Project memory
    │       └── tech-stack.md
    └── notes/              # Optional other custom directories

Tape Mode (Dynamic Context Delivery)

Experimental: This mode is under active development. APIs and behavior may change.

For the latest, install via GitHub: pi install git:github.com/VandeeFeng/pi-memory-md

Note: This mode may consume more tokens. Adjust parameters based on your model's context window and your API quota.

More details tape-design / 中文版

Minimal setting:

{
  "pi-memory-md": {
    ...
    "tape": {
      // "enabled": false,
      "anchor": {
        "keywords": {
          "global": ["refactor", "migration"],
          "project": ["tape", "Emacs"]
        }
      }
    }
  }
}

Then use /memory-anchor to create an anchor manually, or let anchors be created automatically when configured keywords are triggered. If manual mode is off, capable models may also create anchors autonomously when they judge it useful.

If you want to jump to the conversation around an anchor and restart from there, /tree and the anchors in this session are all there with a customizable anchor label in pi TUI.

Note: pi-memory-md does not create labels through pi's built-in label API. These anchor labels are only displayed in the /tree UI. Built-in pi labels are written into session records, and this project intentionally avoids that invasive design.

This may cause some unnecessary runtime memory usage, but I consider the tradeoff necessary.

Tape vs Delivery Modes

Tape is an independent feature that can be enabled alongside either delivery mode. It does not change the delivery mechanism; it changes which memory files are selected.

Tape	Delivery mode	Behavior
Disabled	message-append	Sends memory once as a hidden custom message on the first agent turn
Disabled	system-prompt	Rebuilds memory and appends it to the system prompt on every agent turn
Enabled	message-append	Sends tape-selected memory once as a hidden custom message on the first agent turn
Enabled	system-prompt	Rebuilds tape-selected memory and appends it to the system prompt on every agent turn

With tape enabled, the delivered content is still a memory index/summary for the model, but the file list is chosen by tape-aware selection logic instead of the basic project scan. In smart mode, the delivered list can also include recently active project file paths inferred from tool usage, plus a recent focus summary for each selected file showing the most recently attended read / edit ranges inside the same effective smart-scan window. Stale paths from old tape history are ignored when the file no longer exists.

A delivered tape hidden message looks like:

<memory_context mode="tape">
<instructions>
Tape is enabled for this conversation. Use tape tools when you need anchors or tape history.
Handoff mode: manual. `tape_handoff` is blocked unless the keyword is triggered or user create manually.
</instructions>
<memory_files>
- path: core/USER.md
  priority: high
  description: User profile and preferences
  tags: user, profile, preferences
  recent focus: read 12-28
</memory_files>
<active_project_files>
- path: /path/to/project/file
  priority: high
  recent focus: read 340-420, read 590-677, edit 340-399
</active_project_files>
</memory_context>

Tape Anchors

Anchors are named checkpoints that correspond to pi session entries, marking important transitions in your conversation. They enable efficient context reconstruction and are mirrored into pi /tree labels:

Each line in the tape anchor store is a JSON record:

{"id":"1234567890-abc123","timestamp":"2026-04-04T12:00:00.000Z","name":"task/begin","type":"handoff","meta":{"summary":"Working on feature X","purpose":"feature","trigger":"manual"},"sessionId":"019dbd12-90b7-72b1-a88d-843706db32de","sessionEntryId":"446b6c33"}

Each anchor has:

• id: A stable unique identifier, auto-generated from sessionEntryId:timestamp:name
• name: A human-readable label (e.g., session/new, task/begin)
• type: Anchor type - session for lifecycle anchors, handoff for manual/semantic transitions
• sessionId: The pi session this anchor belongs to
• sessionEntryId: The associated session entry ID for tree mirroring
• timestamp: ISO timestamp of when the anchor was created
• meta: Optional metadata including summary, trigger, keywords, purpose. purpose is a 1-2 word label (e.g., feature, review, deploy). trigger can be direct (agent auto), keyword (configured keywords matched), or manual (explicit user/tool call)

In short, tape anchors are markers that connect user intent with conversation history. When a user asks the agent to retrieve relevant information from a large memory space, the real query is often not a precise string match. It is more often a vague intention, decision, or task transition that appeared earlier in the conversation. Anchors preserve those moments as explicit markers, which can be more useful than only optimizing RAG-style retrieval over raw text or database records.

Stored within pi session entries, tape anchors link intent back to the exact place where it appeared in the session history and to the larger body of memory data around it. This makes important moments precisely locatable and traceable: context delivery can reconstruct the relevant memory path from the anchor instead of searching through everything blindly. It can then select relevant memory files and recently active project files around those points, optionally including concise recent focus hints like read 340-420 or edit 390-399.

Instead of asking the LLM to infer the user's intent from vague semantic signals later, it is better to record that intent when the user expresses it.

Large context windows do not remove the need for careful context control. For a specific task, the most useful context is still the context that has been selected and shaped precisely. Before relying on RAG, traditional marking, indexing, and search discipline still matter. The quality of text given to the LLM, and the way that information is recorded and managed, directly affect how relevant the model's answers will be once the context grows large.

Beyond context engineering, tape anchors is an implementation of text recording and management.

Keywords make this intent-recording process more practical. They act as lightweight signals for moments when the user is likely expressing an important intention, decision, or transition. Instead of waiting for future retrieval to guess what mattered, keyword detection can guide the agent to create a keyword anchor at the moment the intent appears.

Keyword detection sends a hidden message that asks the agent to consider creating a keyword anchor, and the agent can still refuse when the anchor would not be useful. Anchor names are also mirrored into pi /tree labels for the session nodes they attach to, with stale labels cleaned up before resync.

Lifecycle anchors (session/*) are created automatically, while handoff anchors can be created manually via /memory-anchor. When mode: "manual" is set, direct tape_handoff calls are blocked, so the agent will not create anchors on its own. Keyword-matched hidden instructions and /memory-anchor still work, keeping explicit user control available.

The combination of anchors and keywords closes the loop: intent -> memory data -> intent, while keeping automation under user control.

Prompts should evolve into intent.

Tape Review

/memory-review opens an interactive overlay for browsing tape anchors — a dedicated visual panel for jumping across anchors. Select an anchor to jump directly to the first assistant entry after it in the session tree.

The panel provides:

• Timeline view: Browse all anchors in the current project chronologically
• Keyword relations: Visual connections between anchors and their keywords
• Stats overview: Quick summary of anchor counts, types, and distributions
• Fuzzy search: Type / to filter anchors across names, summaries, purposes, triggers, keywords, and timestamps — press Esc or Ctrl+c to leave search input
• Anchor deletion: Select an anchor and press Ctrl+d to delete it

The panel only helps you land on the right anchor. After jumping there, any deeper branching or tree operations still belong in Pi's native /tree panel. This design is intentionally non-invasive — it uses pi's native APIs without custom TUI rendering, so it won't break across pi versions.

Full Configuration

{
  "pi-memory-md": {
    ...
    "localPath": "~/.pi/memory-md",
    "tape": {
      // Run tape only inside a Git repository by default
      // Uses `git rev-parse --show-toplevel`; if it fails, tape is skipped
      "onlyGit": true, // default

      // Absolute directory paths where tape is always disabled
      // Built-in system/temp directories are also excluded by default
      "excludeDirs": [
        "/absolute/path/to/sandbox"
      ],

      "context": {
        // "smart": ranks memory files plus recent project file activity from session history (default)
        //          repeated accesses get diminishing returns, edit/write outrank plain reads,
        //          recent accesses get a recency bonus, missing/stale paths are ignored,
        //          and handoff boosts only apply near the latest anchors
        // "recent-only": most recently modified memory files only
        "strategy": "smart", // default

        // Max files to deliver into LLM context
        "fileLimit": 10, // default

        // Smart-mode pi session history scan range: [startHours, maxHours]
        // Scans history incrementally by 24-hour steps, starting from startHours.
        // Stops and uses the result once the sample reaches MIN_SMART_ACCESS_SAMPLES (5).
        // Otherwise keeps expanding until maxHours is reached.
        "memoryScan": [72, 168], // default

        // "alwaysInclude" is deprecated
        // Files or directories to always include in context (optional, defaults to empty)
        "whitelist": [
          "core/USER.md",
          "docs/tape-design.md"
        ],

        // Files or directories to always exclude from context (optional, defaults to empty)
        // Other paths still go through rg ignore rules first, then the built-in default ignore list.
        "blacklist": [
          "node_modules",
          "dist"
        ]
      },
      "anchor": {
        // "auto": LLM may create handoff anchors when it decides they are useful
        // "manual": direct tape_handoff is hard-blocked
        // hidden keyword instructions and /memory-anchor still work in manual mode
        "mode": "auto", // default

        // Prefix mirrored into pi /tree labels for anchor nodes
        "labelPrefix": "⚓ ", // default

        "keywords": {
          // Match against user prompts with length in [10, 300]
          // When matched, send a hidden instruction about the tape_handoff tool call
          // It stays in the same agent turn: no extra LLM request, only extra tokens in the current request
          // This gives the agent room to refuse when creating a keyword anchor is not necessary at all
          // Strongly recommended! Keywords make anchor creation much smarter - customize based on your focus areas
          "global": ["refactor", "migration"],
          "project": ["tape", "Emacs"]
        }
      },

      // Custom tape path (optional)
      // If not set, default is {localPath}/TAPE: ~/.pi/memory-md/TAPE
      // Anchor index files (.jsonl) will be stored directly under this path
      "tapePath": "/custom/path/to/tape"
    }
  }
}

Tape Tools & Slash Command

Tool	Parameters	Description
/memory-anchor	<prompt>	Slash command that asks the LLM to derive and create a manually authorized handoff anchor
/memory-review	[limit] default: 50, max: 100	Slash command that opens an interactive Memory Review overlay for browsing anchors by timeline, keyword relations, stats, and / fuzzy search
tape_handoff	{name, summary?, purpose?}	Create a handoff anchor checkpoint in the tape
tape_list	{limit?: number}	List all anchor checkpoints
tape_delete	{id}	Delete an anchor checkpoint by id
tape_info	{}	Get tape statistics and information
tape_search	{query?, kinds?, limit?, sinceAnchor?, anchorName?, anchorType?, anchorSummary?, anchorPurpose?, anchorKeywords?}	Search tape entries by text or type, with structured anchor-field filters
tape_read	{afterAnchor?, lastAnchor?, betweenAnchors?, betweenDates?, query?, kinds?, limit?}	Read tape entries as formatted messages
tape_reset	{archive?: boolean}	Reset the tape with a new session lifecycle anchor

Note: Tape tools are registered when a tape block exists in config (opt-out: set "enabled": false). They provide anchor-based context management inspired by bub's tape mechanism.

Reference

• Introducing Context Repositories: Git-based Memory for Coding Agents | Letta
• https://tape.systems
• https://bub.build/
• https://github.com/bubbuild/bub/tree/main/src/bub