pi-agent-memory-repo

Cognition-spec compliant, Git-backed persistent memory repository package for the Pi coding agent and OMP (pi.dev / @earendil-works/pi-coding-agent).

English | 中文说明

pi-agent-memory-repo equips the Pi agent with durable, inspectable, and cross-session memory backed by standalone Git repositories. It faithfully implements the open Agent Memory Repo specification originated by Cognition (creators of Devin).

Features

• Cognition Open Spec Compliance:
  • Root entry point MEMORY.md loaded automatically at session start (< 50 lines recommended).
  • Wiki-like cross-linking via [[path]] syntax (omitting .md for Markdown notes, preserving extensions for non-markdown assets).
  • Single-line bullet entries with structured key-value metadata: - <Fact> [source: ...; added: YYYY-MM-DD]
  • Git-backed durability: every write, initialization, and consolidation commits changes with informative messages.
• Dual-Scope Memory Architecture:
  • Universal Agent Memory (~/.pi/agent-memory/): User preferences, communication tone, and cross-project knowledge.
  • Project-Level Memory (<workspace>/.pi/memory/): Codebase architecture, build/test quirks, and session investigation findings.
• Autonomous Memory Consolidation ("Dreaming"):
  • Identifies cross-session patterns across observations.
  • Merges near-duplicate entries and combines sources.
  • Resolves contradictions between older and newer rules.
  • Synthesizes abstracted higher-level guidelines into topics/patterns.md.
• Core Agent Tools:
  • memory_recall: Keyword and relevance search across scopes.
  • memory_write: Appends single-line entries, creates topic files, and updates MEMORY.md index.
  • memory_read: Reads memory files and inspects resolved [[wikilinks]].
  • memory_list: Lists directory trees, entry counts, and broken link diagnostics.
• Interactive Slash Commands:
  • /init memory [global|project|all]: Initializes memory repositories and Git commits.
  • /remember [notes]: Autonomously distills conversation key points, presents an interactive TUI proposal modal, and writes to memory upon user approval.
  • /dreaming [global|project|all]: Runs pattern detection and memory consolidation.
  • /status: Displays memory repository paths, commit counts, and link health.
• Instant Context Injection:
  • Automatically hooks into Pi's context and session_start lifecycle events to inject <agent_memory> at the start of conversation turns.

Installation

Via Pi CLI (Recommended for pi.dev/packages)

Install the package directly into Pi using the package manager:

# User-level (global across all projects)
pi install npm:pi-agent-memory-repo

# Project-level (saved into <workspace>/.pi/settings.json)
pi install --local npm:pi-agent-memory-repo

# Try in a single session without saving
pi -e npm:pi-agent-memory-repo

Via npm (Library Dependency)

Install as a standard Node.js dependency:

npm install pi-agent-memory-repo

Local Development / From Git

# From git repository
pi install git:github.com/chensirui2008/pi-agent-memory-repo

# From local directory
pi install /path/to/pi-agent-memory-repo

# Or run directly with extension flag
pi --extension /path/to/pi-agent-memory-repo/dist/src/index.js

OMP (oh-my-pi)

This package also provides an independent OMP entry point (dist/src/omp.js). OMP loads omp.extensions; Pi continues to load pi.extensions. The OMP entry does not import the Pi TUI or invoke the Pi registration function.

Build and try the dedicated entry locally:

npm run build
omp -e ./dist/src/omp.js

# Install the local package as an OMP plugin
omp plugin link /absolute/path/to/pi-agent-memory-repo

In the active OMP user or project config.yml, disable its built-in memory backend:

memory:
  backend: off

This plugin uses its own memory_* tools and does not manage OMP's built-in /memory, ctx.memory, or memory:// URLs. See the official extension loading documentation and extension API.

OMP leaves /init and /status available to the host. memory_recall, memory_read and memory_list use OMP's read approval tier; memory_write uses write. Their parameters and storage format match Pi.

Pi and OMP share ~/.pi/agent-memory and <workspace>/.pi/memory, including overrides from AGENT_MEMORY_GLOBAL_DIR and AGENT_MEMORY_PROJECT_DIR. No data migration is required. Use the hosts sequentially when writing to the same repository; simultaneous multi-process writes are not guaranteed safe.

OMP loads a snapshot of both root MEMORY.md files at session start or session switch. The snapshot stays fixed during the session, including after /remember, /init-memory, /dreaming, or memory_write. Start or load a session to refresh it. Tools always read the latest files. Snapshot loading never initializes or writes repositories; read failures produce diagnostics without blocking conversation.

Explicit /remember notes generate only note candidates. Without a note, OMP uses the current model through a tool-free ephemeral turn, which does not enter session history. A 20-second cancellation deadline, unavailable model, invalid JSON or provider failure triggers heuristic extraction with a downgrade notice. A valid empty proposal stays empty.

In the TUI, choose an entry to toggle its checkbox, then choose Save selected memories; Cancel or Escape discards the proposal. Other interactive hosts show the full proposal and require confirmation. With no UI (including RPC --no-ui), explicit notes save directly; automatic extraction only displays a proposal. Cancellation and empty proposals never create placeholder memories. If a Git commit fails after writing, the output explicitly reports that files were written but the commit is incomplete.

For disposable local verification, set both directory overrides and isolate OMP configuration before using commands:

AGENT_MEMORY_GLOBAL_DIR=/tmp/memory-demo/global \
AGENT_MEMORY_PROJECT_DIR=/tmp/memory-demo/project \
PI_CODING_AGENT_DIR=/tmp/memory-demo/agent \
omp --no-extensions -e ./dist/src/omp.js

Place memory.backend: off in that disposable agent directory's config.yml. To disable the plugin later, remove its loading configuration or uninstall its OMP link; memory files remain on disk.

Memory Repository Structure

Each memory repository (Universal ~/.pi/agent-memory and Project <workspace>/.pi/memory) adheres to the layout:

<memory-repo-root>/
├── .git/                      # Dedicated Git repository
├── MEMORY.md                  # Root entry point (< 50 lines)
├── topics/                    # Categorized topic notes
│   ├── notes.md               # General notes
│   ├── user_preferences.md   # Universal preferences & habits
│   ├── architecture.md        # Architectural invariants
│   ├── testing_rules.md       # Test benchmarks & CI quirks
│   └── patterns.md            # Synthesized cross-session insights
└── scripts/                   # Optional benchmark or test scripts

Usage

1. Interactive Slash Commands

• Initialize Memory:

  /init memory
  /init memory project
  /init memory global

• Record Memories:

  /remember
  /remember User prefers strict TypeScript with zero any
  /remember Always pass HOME=/tmp when running sandboxed commands

  (Running /remember autonomously summarizes the conversation, distills key points, and renders an interactive TUI proposal modal. Users can navigate [↑/↓], toggle items [Space], and approve [Enter/y] before memories are committed to Git. In RPC mode, the proposal uses the supported confirmation dialog.)
• Consolidate & Dream:

  /dreaming
  /dreaming project

• Inspect Status:

  /status

2. Tools for LLMs

The extension registers four standard tools:

Configuration

The following environment variables can customize storage paths:

中文说明

pi-agent-memory-repo 是专为 Pi 编程智能体（pi.dev）设计的持久化记忆扩展包，完整遵循 Cognition（Devin 团队）发布的 Agent Memory Repo 开放规范。

核心亮点

1. Git 原生驱动：所有记忆的增删、整理、索引更新均自动进行 Git Commit 记录，历史可溯、完全透明、可协同共享。
2. 双层记忆架构：
   • 全局记忆（Universal Memory）：存储在 ~/.pi/agent-memory/，跨项目记录用户编码习惯、偏好和交互风格。
   • 项目记忆（Project Memory）：存储在 <workspace>/.pi/memory/，记录当前代码库架构规律、测试注意事项和调试结论。
3. 梦境记忆固化（Dreaming）：跨会话自动扫描、去重、解决冲突，并将高频共性规则归纳至 topics/patterns.md。
4. 轻量与开箱即用：自带 4 个标准大模型 Tool，4 个交互式斜杠指令，并在会话启动时无缝注入上下文。
5. 自主提炼与 TUI 提案审批：/remember 自主提炼会话重点，以交互式终端 TUI 呈现记忆提案，支持键盘勾选导航；RPC 模式使用确认对话框，用户同意后才提交写入 Git。

快速安装

# 全局安装到 Pi 智能体
pi install npm:pi-agent-memory-repo

# 项目级安装
pi install --local npm:pi-agent-memory-repo

Development & Testing

# Compile TypeScript
npm run build

# Run unit and integration tests
npm test

# Dry-run npm pack to verify bundle contents
npm pack --dry-run

License

MIT © 2026 Pi Agent Team