dancepower22/pi-memory-evo

Persistent Memory & Self-Evolution (memory)

Core Principle: Save proactively, don't wait for the user to ask. Turn the user's environment into a system that "understands you better the more you use it": Three-layer granular memory (fact/pattern/lesson) + session summaries + lesson routing (self-evolution).

🚀 Session Start (each new session)

1. If ~/.agents/memory/MEMORY.md exists, read it first to quickly understand the user's background, preferences, and recent sessions.
2. When details are needed, use memory.py get <id> or memory.py search <keyword> to dive deeper.
3. Show the user the key remembered information (briefly) to demonstrate continuity.

📌 Active Saving (ALWAYS ACTIVE, save on encounter, don't wait for session end)

When any of the following situations occur, immediately call memory.py add <type> <content> to save:

Type	When to Save	Example
fact	User reveals a preference/habit/identity info; important project decisions, tech choices, conventions; user explicitly says "remember"	"User prefers Chinese replies" "Project uses pnpm + TypeScript"
pattern	Same behavior/issue appears 2+ times (including this time)	"Every time a skill is installed, the user asks to evaluate dependencies first"
lesson	Experience learned from a pitfall, troubleshooting conclusion, discovered gotcha	"DuckDuckGo's ddgs default backend goes through Yandex and times out; must use backend='html'"

• Saving can include --tag a,b for easier retrieval.
• The tool automatically performs approximate deduplication; duplicate content will prompt rather than store again.

🗂️ Session End (or user asks "summarize session / solidify")

Execute in order:

1. Review this session and extract 2-5 most important pieces of information.
2. Classify and save: fact (new preferences/decisions) → pattern (new regularities) → lesson (new experiences).
3. Lesson Routing (Self-Evolution): For each lesson, determine:
   • If it is a reusable methodology (e.g., standard workflow for a certain task) → create or update a skill in ~/.agents/skills/ (using write/edit tools) so it takes effect automatically next session;
   • If it is a one-time fact → save as fact;
   • If it is environment/account specific (e.g., configuration needed for a tool) → save as lesson only.
4. Use memory.py session-save "<one-sentence summary of this session>" --key keyword1,keyword2 to save the session record.
5. Run memory.py sync to refresh the MEMORY.md overview.

🔍 Querying Memory

When the user asks "I said before / last time / my preferences" etc. → memory.py search <keyword>; list all → memory.py list.

⚙️ Quick Tool Reference

P=~/.agents/skills/pi-memory-evo/memory.py
$P init                       # First-time initialization
$P add fact "content" --tag preference    # Save fact/pattern/lesson
$P session-save "summary" --key a  # Save session summary
$P search keyword                # Search
$P list                          # List all
$P get <id> / update <id> <new content> / delete <id>   # Management
$P stats                         # Statistics
$P sync                          # Refresh overview MEMORY.md

📂 Storage Locations

• Data: ~/.agents/memory/memory.json (four-layer memory, JSON)
• Overview: ~/.agents/memory/MEMORY.md (read at session start)
• Skill itself: ~/.agents/skills/pi-memory-evo/ (tool + this documentation)

⚠️ Boundaries

• Do not store sensitive credentials: tokens, passwords, keys are never saved.
• Respect user wishes: if the user says "don't record this", it is not saved; if the user says "forget X", call delete on the corresponding entry.
• Memory is an aid, not a replacement for confirmation: for important operations, the user's current intent still takes precedence.