A pi extension for durable, markdown-based agent memory across sessions.

pi-memory is currently in early implementation. The package is installable as a pi extension and initializes a private, markdown-first storage foundation; higher-level memory tools are intentionally minimal until retrieval, compaction, and promotion workflows are implemented.

Build a memory system for pi that improves cross-session work without bloating the active context window.

The design target is:

• durable across sessions
• inspectable as plain files
• safe against stale or overconfident memory
• useful without extra infrastructure
• integrated with pi lifecycle hooks and compaction
• compatible with wiki-backed project truth and Forge-style implementation planning

From a local checkout:

pi install ./pi-memory

For one-off testing:

pi -e ./index.ts

After publishing to GitHub:

pi install git:github.com/<owner>/pi-memory

This early package registers:

• /memory-status command
• memory_status tool

On session start it initializes a private hybrid global/project storage layout under ~/.pi/agent/memory/.

Memory is a pipeline, not a single file:

session evidence -> episodic memory -> semantic memory -> wiki truth -> selective recall

The system separates what happened from what is currently true:

• Session evidence: raw pi session references, tool calls, user decisions, failures, and outputs.
• Episodic memory: timestamped summaries of sessions or tasks.
• Semantic memory: durable facts, preferences, project decisions, conventions, and lessons.
• Wiki truth: curated project knowledge that should influence future work.
• Selective recall: small, relevant memory injected or retrieved on demand.

1. Memory is a lifecycle, not a note dump.
2. Store only what cannot be cheaply derived from files, git, logs, or docs.
3. Separate episodic evidence from semantic facts.
4. Prefer markdown and small manifests before databases.
5. Use frozen session snapshots for prompt-cache stability.
6. Treat compaction as a consolidation checkpoint.
7. Inject selectively; never dump the whole memory store into context.
8. Track provenance, confidence, and freshness for every durable memory.
9. Capture positive feedback as well as corrections.
10. Do not silently promote session evidence into project truth.

pi-memory/
  index.ts              # pi extension entrypoint
  package.json          # pi package manifest
  tsconfig.json
  README.md
  LICENSE
  wiki-forge/           # public architecture docs for wiki/Forge workflow

Internal research and reference material lives under reference/ and is gitignored.

The public architecture docs are in wiki-forge/:

• README.md
• sessions.md
• memory-lifecycle.md
• forge-loop.md
• decisions.md
• promotion-policy.md
• project-truth-index.md
• open-questions.md

These docs define how pi-memory should connect raw sessions, durable memory, wiki truth, and Forge implementation work.

• initialize memory directory
• explicit write/read tools
• session evidence references
• markdown storage
• basic manifests

• episode summaries from pi sessions
• candidate semantic memory extraction
• wiki promotion workflow
• Forge-ready follow-up generation

• session-start frozen snapshot
• task-relevant retrieval
• freshness warnings
• pinned memories
• optional qmd semantic search

• session_before_compact flush
• post-session extractor
• deduplication
• stale memory handling
• review/promote commands

• optional relationship/entity index
• multi-agent shared memory
• TUI dashboard
• memory evaluation harness

This repository follows pi package conventions:

{
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./index.ts"]
  }
}

pi loads TypeScript extensions directly, so no build step is required for local development.

Typecheck:

npm run check

Test locally with pi:

npm run test:local

Storage layout foundation implemented. The next implementation area is explicit memory write/read/search tooling.