co-mono/packages/pi-memory-md/skills/memory-management/SKILL.md

name	description
memory-management	Core memory operations for pi-memory-md - create, read, update, and delete memory files

Memory Management

Use this skill when working with pi-memory-md memory files. Memory is stored as markdown files with YAML frontmatter in a git repository.

Design Philosophy

Inspired by Letta memory filesystem:

• File-based memory: Each memory is a .md file with YAML frontmatter
• Git-backed: Full version control and cross-device sync
• Auto-injection: Files in core/ are automatically injected to context
• Organized by purpose: Fixed structure for core info, flexible for everything else

Directory Structure

Base path: Configured via settings["pi-memory-md"].localPath (default: ~/.pi/memory-md)

{localPath}/
└── {project-name}/                  # Project memory root
    ├── core/                        # Auto-injected to context every session
    │   ├── user/                    # 【FIXED】User information
    │   │   ├── identity.md          # Who the user is
    │   │   └── prefer.md            # User habits and code style preferences
    │   │
    │   └── project/                 # 【FIXED】Project information (pre-created)
    │       ├── overview.md          # Project overview
    │       ├── architecture.md      # Architecture and design
    │       ├── conventions.md       # Code conventions
    │       └── commands.md          # Common commands
    │
    ├── docs/                        # 【AGENT-CREATED】Reference documentation
    ├── archive/                     # 【AGENT-CREATED】Historical information
    ├── research/                    # 【AGENT-CREATED】Research findings
    └── notes/                       # 【AGENT-CREATED】Standalone notes

Important: core/project/ is a pre-defined folder under core/. Do NOT create another project/ folder at the project root level.

Core Design: Fixed vs Flexible

【FIXED】core/user/ and core/project/

These are pre-defined and auto-injected into every session:

core/user/ - User information (2 fixed files)

• identity.md - Who the user is (name, role, background)
• prefer.md - User habits and code style preferences

core/project/ - Project information

• overview.md - Project overview
• architecture.md - Architecture and design
• conventions.md - Code conventions
• commands.md - Common commands
• changelog.md - Development history

Why fixed?

• Always in context, no need to remember to load
• Core identity that defines every interaction
• Project context needed for all decisions

Rule: ONLY user/ and project/ exist under core/. No other folders.

Decision Tree

Does this need to be in EVERY conversation?

Yes → Place under core/

• User-related → core/user/
• Project-related → core/project/

No → Place at project root level (same level as core/)

• Reference docs → docs/
• Historical → archive/
• Research → research/
• Notes → notes/
• Other? → Create appropriate folder

Important: core/project/ is a FIXED subdirectory under core/. Always use core/project/ for project-specific memory files, NEVER create a project/ folder at the root level.

YAML Frontmatter Schema

Every memory file MUST have YAML frontmatter:

---
description: "Human-readable description of this memory file"
tags: ["user", "identity"]
created: "2026-02-14"
updated: "2026-02-14"
---

Required fields:

• description (string) - Human-readable description

Optional fields:

• tags (array of strings) - For searching and categorization
• created (date) - File creation date (auto-added on create)
• updated (date) - Last modification date (auto-updated on update)

Examples

Example 1: User Identity (core/user/identity.md)

memory_write(
  path="core/user/identity.md",
  description="User identity and background",
  tags=["user", "identity"],
  content="# User Identity\n\nName: Vandee\nRole: Developer..."
)

Example 2: User Preferences (core/user/prefer.md)

memory_write(
  path="core/user/prefer.md",
  description="User habits and code style preferences",
  tags=["user", "preferences"],
  content="# User Preferences\n\n## Communication Style\n- Be concise\n- Show code examples\n\n## Code Style\n- 2 space indentation\n- Prefer const over var\n- Functional programming"
)

Example 3: Project Architecture (core/project/)

memory_write(
  path="core/project/architecture.md",
  description="Project architecture and design",
  tags=["project", "architecture"],
  content="# Architecture\n\n..."
)

Example 3: Reference Docs (root level)

memory_write(
  path="docs/api/rest-endpoints.md",
  description="REST API reference documentation",
  tags=["docs", "api"],
  content="# REST Endpoints\n\n..."
)

Example 4: Archived Decision (root level)

memory_write(
  path="archive/decisions/2024-01-15-auth-redesign.md",
  description="Auth redesign decision from January 2024",
  tags=["archive", "decision"],
  content="# Auth Redesign\n\n..."
)

Reading Memory Files

Use the memory_read tool:

memory_read(path="core/user/identity.md")

Listing Memory Files

Use the memory_list tool:

# List all files
memory_list()

# List files in specific directory
memory_list(directory="core/project")

# List only core/ files
memory_list(directory="system")

Updating Memory Files

To update a file, use memory_write with the same path:

memory_write(
  path="core/user/identity.md",
  description="Updated user identity",
  content="New content..."
)

The extension preserves existing created date and updates updated automatically.

Folder Creation Guidelines

core/ directory - FIXED structure

Only two folders exist under core/:

• user/ - User identity and preferences
• project/ - Project-specific information

Do NOT create any other folders under core/.

Root level (same level as core/) - COMPLETE freedom

Agent can create any folder structure at project root level (same level as core/):

• docs/ - Reference documentation
• archive/ - Historical information
• research/ - Research findings
• notes/ - Standalone notes
• examples/ - Code examples
• guides/ - How-to guides

Rule: Organize root level in a way that makes sense for the project.

WARNING: Do NOT create a project/ folder at root level. Use core/project/ instead.

Best Practices

DO:

• Use core/user/identity.md for user identity
• Use core/user/prefer.md for user habits and code style
• Use core/project/ for project-specific information
• Use root level for reference, historical, and research content
• Keep files focused on a single topic
• Organize root level folders by content type

DON'T:

• Create folders under core/ other than user/ and project/
• Create other files under core/user/ (only identity.md and prefer.md)
• Create a project/ folder at root level (use core/project/ instead)
• Put reference docs in core/ (use root docs/)
• Create giant files (split into focused topics)
• Mix unrelated content in same file

Maintenance

Session Wrap-up

After completing work, archive to root level:

memory_write(
  path="archive/sessions/2025-02-14-bug-fix.md",
  description="Session summary: fixed database connection bug",
  tags=["archive", "session"],
  content="..."
)

Regular Cleanup

• Consolidate duplicate information
• Update descriptions to stay accurate
• Remove information that's no longer relevant
• Archive old content to appropriate root level folders

When to Use This Skill

Use memory-management when:

• User asks to remember something for future sessions
• Creating or updating project documentation
• Setting preferences or guidelines
• Storing reference material
• Building knowledge base about the project
• Organizing information by type or domain
• Creating reusable patterns and solutions
• Documenting troubleshooting steps

Related Skills

• memory-sync - Git synchronization operations
• memory-init - Initial repository setup
• memory-search - Finding specific information
• memory-check - Validate folder structure before syncing

Before Syncing

IMPORTANT: Before running memory_sync(action="push"), ALWAYS run memory_check() first to verify the folder structure is correct:

# Check structure first
memory_check()

# Then push if structure is correct
memory_sync(action="push")

This prevents accidentally pushing files in wrong locations (e.g., root project/ instead of core/project/).