trusty-memory

trusty-memory

Persistent memory system using the Memory Palace metaphor for organizing context across sessions. Replaces mcp__kuzu-memory__* tools.

When to Use

• Session start: Recall relevant context for the current task
• Decision moments: Store key architectural/design decisions
• Learning capture: Remember new patterns, conventions, gotchas discovered
• Relationship tracking: Assert facts in the knowledge graph (X depends on Y, A replaces B)
• Session end: Persist outcomes and next steps

Do NOT use for: ephemeral scratch notes, code snippets (use trusty-search), or content that belongs in source files.

Architecture

Palace (project)     e.g. "claude-mpm"
  └── Wing (area)    e.g. "Backend"
        └── Room     e.g. "Backend", "Frontend", "Testing", "Planning",
                          "Documentation", "Research", "Configuration",
                          "Meetings", "General"
              └── Closet (sub-category)
                    └── Drawer (memory item: uuid, content, tags, importance)

Progressive Retrieval Layers

Always try memory_recall first. Escalate to memory_recall_deep only if results are insufficient.

Tool Reference

Retrieval

memory_recall — Fast progressive retrieval (L0+L1+L2). Use this first.

mcp__trusty-memory__memory_recall(
  query="how does the migration registry work",
  room="Backend",        # optional filter
  limit=10               # optional
)

memory_recall_deep — Full HNSW deep search (L3). Use when memory_recall insufficient.

mcp__trusty-memory__memory_recall_deep(
  query="rare edge case in hook dispatcher",
  limit=20
)

memory_list — Browse drawers by room/tag (no semantic query).

mcp__trusty-memory__memory_list(room="Planning", tag="release-workflow")

Storage

memory_remember — Store a drawer.

mcp__trusty-memory__memory_remember(
  content="The migration runner uses run_pending_migrations() at startup; state in ~/.claude-mpm/migrations.json",
  room="Backend",
  tags=["migrations", "startup"],
  importance=0.8         # 0.0-1.0; higher = more likely to appear in L1
)

memory_forget — Delete by UUID.

mcp__trusty-memory__memory_forget(drawer_id="<uuid>")

Palace Management

mcp__trusty-memory__palace_list()
mcp__trusty-memory__palace_info(palace="claude-mpm")
mcp__trusty-memory__palace_create(name="new-project")

Knowledge Graph (temporal triples)

kg_assert — Assert a (subject, predicate, object) fact.

mcp__trusty-memory__kg_assert(
  subject="trusty-memory",
  predicate="replaces",
  object="kuzu-memory"
)

kg_query — Query triples for a subject.

mcp__trusty-memory__kg_query(subject="trusty-memory")

Room Type Selection

When unsure, prefer the most-specific room. Tags handle the rest.

KG Triple Patterns

Use consistent predicates for queryable graphs:

Workflow Protocols

Session Start Protocol

1. Auto-loaded: L0 identity + L1 top-15 drawers appear in context automatically.
2. Targeted recall: For task-specific context:

   memory_recall(query="<current task domain>", limit=10)
   

3. Check KG for relevant entity relationships:

   kg_query(subject="<entity being modified>")
   

Session End Protocol

For each significant outcome, persist it:

1. Decisions → memory_remember with high importance (0.7-0.9)

   memory_remember(
     content="Decided to consolidate hook scripts under claude-hook-fast.sh; old per-event scripts deprecated",
     room="Backend",
     tags=["hooks", "decision"],
     importance=0.85
   )
   

2. Relationships → kg_assert

   kg_assert(subject="claude-hook-fast.sh", predicate="replaces", object="per-event-hook-scripts")
   

3. Gotchas / learnings → memory_remember with tags for discoverability

   memory_remember(
     content="release-publish requires `claude-mpm gh switch` to bobmatnyc first; bob-duetto account causes auth failures",
     room="Configuration",
     tags=["release", "gotcha", "github-auth"],
     importance=0.9
   )
   

Recall vs Recall-Deep Decision

Importance Scoring

L1 surfaces the top 15 by importance — score accordingly.

Migration from kuzu-memory

Integration with trusty-search

Common pattern: search → understand → remember.

# 1. Find code with trusty-search
search_code(query="migration runner", query_type="Definition")

# 2. After investigating, persist the learning
memory_remember(
  content="Migration runner pattern: registry.py registers each migrate_*.py module; run_pending_migrations iterates by version",
  room="Backend",
  tags=["migrations", "pattern"],
  importance=0.75
)

Best Practices

• Be specific: "Release workflow requires bobmatnyc gh account" beats "Check gh account before releasing"
• Include WHY: Decision rationale beats decision alone
• Tag generously: Tags enable cross-room discovery
• Use KG for relationships: Don't bury "X replaces Y" in prose — assert it
• Update over duplicate: Forget stale drawers when superseded
• Prefer recall over recall_deep: Save the expensive call for when you need it