Remember - Store Decisions and Patterns

Architecture

1. Knowledge Graph: Entity and relationship storage via

   mcp__memory__create_entities

   and

   mcp__memory__create_relations

   - FREE, zero-config, always works

• Zero configuration required - works out of the box
• Explicit relationship queries (e.g., "what does X use?")
• Cross-referencing between entities
• No cloud dependency

• Extracts capitalized terms as potential entities (PostgreSQL, React, pgvector)
• Detects agent names (database-engineer, backend-system-architect)
• Identifies pattern names (cursor-pagination, connection-pooling)
• Recognizes "X uses Y", "X recommends Y", "X requires Y" relationship patterns

Usage

Store Decisions (Default)

/remember <text>
/remember --category <category> <text>
/remember --success <text>     # Mark as successful pattern
/remember --failed <text>      # Mark as anti-pattern
/remember --success --category <category> <text>

# Agent-scoped memory
/remember --agent <agent-id> <text>         # Store in agent-specific scope
/remember --global <text>                   # Store as cross-project best practice

Flags

--success

--failed

--category <cat>

--agent <agent-id>

--global

Categories

• decision

  - Why we chose X over Y (default)

• architecture

  - System design and patterns

• pattern

  - Code conventions and standards

• blocker

  - Known issues and workarounds

• constraint

  - Limitations and requirements

• preference

  - User/team preferences

• pagination

  - Pagination strategies

• database

  - Database patterns

• authentication

  - Auth approaches

• api

  - API design patterns

• frontend

  - Frontend patterns

• performance

  - Performance optimizations

Outcome Flags

• --success

  - Pattern that worked well (positive outcome)

• --failed

  - Pattern that caused problems (anti-pattern)

Workflow

1. Parse Input

Check for --success flag → outcome: success
Check for --failed flag → outcome: failed
Check for --category <category> flag
Check for --agent <agent-id> flag → agent_id: "ork:{agent-id}"
Check for --global flag → use global user_id
Extract the text to remember
If no category specified, auto-detect from content

2. Auto-Detect Category

3. Extract Lesson (for anti-patterns)

• "should have", "instead use", "better to"
• If not found, prompt user: "What should be done instead?"

4. Extract Entities from Text

1. Find capitalized terms (PostgreSQL, React, FastAPI)
2. Find agent names (database-engineer, backend-system-architect)
3. Find pattern names (cursor-pagination, connection-pooling)
4. Find technology keywords (pgvector, HNSW, RAG)

5. Create Graph Entities (PRIMARY)

mcp__memory__create_entities

{
  "entities": [
    {
      "name": "pgvector",
      "entityType": "Technology",
      "observations": ["Used for vector search", "From remember: '{original text}'"]
    },
    {
      "name": "database-engineer",
      "entityType": "Agent",
      "observations": ["Recommends pgvector for RAG"]
    }
  ]
}

• Capitalized single words ending in common suffixes: Technology (PostgreSQL, FastAPI)
• Words with hyphens matching agent pattern: Agent (database-engineer)
• Words with hyphens matching pattern names: Pattern (cursor-pagination)
• Project context: Project (current project name)
• Failed patterns: AntiPattern

6. Create Graph Relations

mcp__memory__create_relations

{
  "relations": [
    {
      "from": "database-engineer",
      "to": "pgvector",
      "relationType": "RECOMMENDS"
    },
    {
      "from": "pgvector",
      "to": "RAG",
      "relationType": "USED_FOR"
    }
  ]
}

7. Confirm Storage

✅ Remembered SUCCESS (category): "summary of text"
   → Stored in knowledge graph
   → Created entity: {entity_name} ({entity_type})
   → Created relation: {from} → {relation_type} → {to}
   📊 Graph: {N} entities, {M} relations

❌ Remembered ANTI-PATTERN (category): "summary of text"
   → Stored in knowledge graph
   → Created entity: {anti-pattern-name} (AntiPattern)
   💡 Lesson: {lesson if extracted}

✓ Remembered (category): "summary of text"
   → Stored in knowledge graph
   → Created entity: {entity_name} ({entity_type})
   📊 Graph: {N} entities, {M} relations

Examples

Basic Remember (Graph Only)

/remember Cursor-based pagination scales well for large datasets

✓ Remembered (pagination): "Cursor-based pagination scales well for large datasets"
   → Stored in knowledge graph
   → Created entity: cursor-pagination (Pattern)
   📊 Graph: 1 entity, 0 relations

Anti-Pattern

/remember --failed Offset pagination caused timeouts on tables with 1M+ rows

❌ Remembered ANTI-PATTERN (pagination): "Offset pagination caused timeouts on tables with 1M+ rows"
   → Stored in knowledge graph
   → Created entity: offset-pagination (AntiPattern)
   💡 Lesson: Use cursor-based pagination for large datasets
   📊 Graph: 1 entity, 0 relations

Agent-Scoped Memory

/remember --agent backend-system-architect Use connection pooling with min=5, max=20

✓ Remembered (database): "Use connection pooling with min=5, max=20"
   → Stored in knowledge graph
   → Created entity: connection-pooling (Pattern)
   → Created relation: project → USES → connection-pooling
   📊 Graph: 1 entity, 1 relation
   🤖 Agent: backend-system-architect

Duplicate Detection

1. Query graph with

   mcp__memory__search_nodes

   for entity names
2. If exact entity exists:
   • Add observation to existing entity via

     mcp__memory__add_observations

   • Inform user: "✓ Updated existing entity (added observation)"
3. If similar pattern found with opposite outcome:
   • Warn: "⚠️ This conflicts with an existing pattern. Store anyway?"

File-Based Memory Updates

.claude/memory/MEMORY.md

• PREFER Edit over Write to preserve existing content and avoid overwriting
• Use stable anchor lines:

  ## Recent Decisions

  ,

  ## Patterns

  ,

  ## Preferences

• See the

  memory

  skill's "Permission-Free File Operations" section for the full Edit pattern
• This applies to the calling agent's file operations, not to the knowledge graph operations above

Related Skills

• memory

  - Search, load, sync, visualize (read-side operations)

Error Handling

• If knowledge graph unavailable, show configuration instructions
• If text is empty, ask user to provide something to remember
• If text >2000 chars, truncate with notice
• If both --success and --failed provided, ask user to clarify
• If --agent used without agent-id, prompt for agent selection
• If entity extraction fails, create a generic Decision entity
• If relation creation fails (e.g., entity doesn't exist), create entities first then retry