clanker-agent/packages/pi-memory-md

pi-memory-md

Letta-like memory management for pi using GitHub-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 GitHub repository (private recommended)

# 3. Configure pi
# Add to ~/.pi/agent/settings.json:
{
  "pi-memory-md": {
    "enabled": true,
    "repoUrl": "git@github.com:username/repo.git",
    "localPath": "~/.pi/memory-md"
  }
}

# 4. Start a new pi session
# The extension will auto-initialize and sync on first run

Commands available in pi:

• :memory-init - Initialize repository structure
• :memory-status - Show repository status

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. Append index to conversation via prompt append (not system prompt)
    ↓
5. LLM reads full file content via tools when needed

Why index-only via prompt append? Keeps token usage low while making full content accessible on-demand. The index is appended to the conversation, not injected into the system prompt.

Available Tools

The LLM can use these tools to interact with memory:

Tool	Parameters	Description
memory_init	{force?: boolean}	Initialize or reinitialize repository
memory_sync	`{action: "pull"	"push"	"status"}`	Git operations
memory_read	{path: string}	Read a memory file
memory_write	{path, content, description, tags?}	Create/update memory file
memory_list	{directory?: string}	List all memory files
memory_search	{query, searchIn}	Search by content/tags/description

Memory File Format

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

# Your Content Here

Markdown content...

Directory Structure

~/.pi/memory-md/
└── project-name/
    ├── core/
    │   ├── user/           # Your preferences
    │   │   ├── identity.md
    │   │   └── prefer.md
    │   └── project/        # Project context
    │       └── tech-stack.md
    └── reference/          # On-demand docs

Configuration

{
  "pi-memory-md": {
    "enabled": true,
    "repoUrl": "git@github.com:username/repo.git",
    "localPath": "~/.pi/memory-md",
    "injection": "message-append",
    "autoSync": {
      "onSessionStart": true
    }
  }
}

Setting	Default	Description
enabled	true	Enable extension
repoUrl	Required	GitHub repository URL
localPath	~/.pi/memory-md	Local clone path
injection	"message-append"	Memory injection mode: "message-append" or "system-prompt"
autoSync.onSessionStart	true	Git pull on session start

Memory Injection Modes

The extension supports two modes for injecting memory into the conversation:

1. Message Append (Default)

{
  "pi-memory-md": {
    "injection": "message-append"
  }
}

• Memory is sent as a custom message before the user's first message
• Not visible in the TUI (display: false)
• Persists in the session history
• Injected only once per session (on first agent turn)
• 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": {
    "injection": "system-prompt"
  }
}

• Memory is appended to the system prompt
• Rebuilt and injected on every agent turn
• Always visible to the model in the system context
• Pros: Memory always present in system context, no need to scroll back
• Cons: Higher token usage (repeated on every prompt)

Recommendation: Use message-append (default) for optimal token efficiency. Switch to system-prompt if you notice the model not accessing memory consistently.

Usage Examples

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

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

Pi: [Uses memory_write tool to save your preference]

You can also explicitly request operations:

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

The LLM automatically:

• Reads memory index at session start (appended to conversation)
• Writes new information when you ask to remember something
• Syncs changes when needed

Commands

Use these directly in pi:

• :memory-status - Show repository status
• :memory-init - Initialize repository structure

Reference

• Introducing Context Repositories: Git-based Memory for Coding Agents | Letta