Remember - Store Decisions and Patterns

Store important decisions, patterns, or context in the knowledge graph for future sessions. Supports tracking success/failure outcomes for building a Best Practice Library.

Architecture

The remember skill uses knowledge graph as storage:

1. Knowledge Graph: Entity and relationship storage via mcp__memory__create_entities and mcp__memory__create_relations - FREE, zero-config, always works

Benefits:

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

Automatic Entity Extraction:

• 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)

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

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

Flags

Flag	Behavior
(default)	Write to graph
--success	Mark as successful pattern
--failed	Mark as anti-pattern
--category <cat>	Set category
--agent <agent-id>	Scope memory to a specific agent
--global	Store as cross-project best practice

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)

If neither flag is provided, the memory is stored as neutral (informational).

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

Keywords	Category
chose, decided, selected	decision
architecture, design, system	architecture
pattern, convention, style	pattern
blocked, issue, bug, workaround	blocker
must, cannot, required, constraint	constraint
pagination, cursor, offset, page	pagination
database, sql, postgres, query	database
auth, jwt, oauth, token, session	authentication
api, endpoint, rest, graphql	api
react, component, frontend, ui	frontend
performance, slow, fast, cache	performance

3. Extract Lesson (for anti-patterns)

If outcome is "failed", look for:

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

4. Extract Entities from Text

Step A: Detect entities:

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)

Step B: Detect relationship patterns:

Pattern	Relation Type
"X uses Y"	USES
"X recommends Y"	RECOMMENDS
"X requires Y"	REQUIRES
"X enables Y"	ENABLES
"X prefers Y"	PREFERS
"chose X over Y"	CHOSE_OVER
"X for Y"	USED_FOR

5. Create Graph Entities (PRIMARY)

Use 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"]
    }
  ]
}

Entity Type Assignment:

• 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

Use mcp__memory__create_relations:

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

7. Confirm Storage

For success:

✅ 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

For failed:

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

For neutral:

✓ 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)

Input: /remember Cursor-based pagination scales well for large datasets

Output:

✓ 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

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

Output:

❌ 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

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

Output:

✓ 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

Before storing, search for similar patterns in graph:

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

When updating .claude/memory/MEMORY.md or project memory files:

• 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

• ork: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