/ork:remember

TEXT = "$ARGUMENTS"        # Full argument string, e.g., "We use cursor pagination"
FLAG = "$ARGUMENTS[0]"     # First token — check for --success, --failed, --category, --agent
# Parse flags from $ARGUMENTS[0], $ARGUMENTS[1] etc. (CC 2.1.59 indexed access)
# Remaining tokens after flags = the text to remember

/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

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

1. Normalize: lowercase, strip hyphens/underscores
2. Compare: Levenshtein distance or substring match
3. Match threshold: >= 80% similarity AND same entityType
4. Action: merge via add_observations if match found

// User says: "/remember PostgreSQL handles our vector search"
// Agent immediately creates without checking:
mcp__memory__create_entities({
  "entities": [{
    "name": "PostgreSQL",
    "entityType": "Technology",
    "observations": ["Handles vector search"]
  }]
})
// Graph already had "postgres" (Technology) with 5 observations
// Now there are TWO entities for the same technology

// Step 1: Search for existing entity
mcp__memory__search_nodes({ "query": "PostgreSQL" })
// Returns: { "name": "postgres", "entityType": "Technology", "observations": [...] }

// Step 2: 80%+ match found ("postgresql" vs "postgres") — merge
mcp__memory__add_observations({
  "observations": [{
    "entityName": "postgres",
    "contents": ["Handles vector search"]
  }]
})
// Single entity with all observations consolidated

Entity Types:   Technology | Agent | Pattern | Project | AntiPattern | Decision | Preference
Relation Types: USES | RECOMMENDS | REQUIRES | ENABLES | PREFERS | CHOSE_OVER | USED_FOR

mcp__memory__create_entities({
  "entities": [
    {
      "name": "Express",
      "entityType": "Framework",
      "observations": ["Used for API server"]
    },
    {
      "name": "Redis",
      "entityType": "Cache",
      "observations": ["Session storage"]
    }
  ]
})
// "Framework" and "Cache" are not valid entity types
// These nodes won't appear in type-based queries

mcp__memory__create_entities({
  "entities": [
    {
      "name": "Express",
      "entityType": "Technology",
      "observations": ["Used for API server (framework)"]
    },
    {
      "name": "Redis",
      "entityType": "Technology",
      "observations": ["Session storage (cache layer)"]
    }
  ]
})
// Both map to "Technology" — specifics go in observations

mcp__memory__create_relations({
  "relations": [{
    "from": "backend-api",
    "to": "Redis",
    "relationType": "CACHES_WITH"
  }]
})
// "CACHES_WITH" is not a valid relation type

mcp__memory__create_relations({
  "relations": [{
    "from": "backend-api",
    "to": "Redis",
    "relationType": "USES"
  }]
})
// "USES" is the closest valid relation type

PASS: Contains at least ONE of:
  - A concrete metric (p99, latency, throughput, error rate)
  - A specific configuration value (min=5, max=20, timeout=30s)
  - A named alternative that was rejected and why
  - A reproduction step or trigger condition

FAIL: Contains ONLY:
  - Adjectives without context ("good", "fast", "better", "useful")
  - Tautologies ("PostgreSQL is a database")
  - Vague recommendations ("consider using X")

mcp__memory__create_entities({
  "entities": [{
    "name": "cursor-pagination",
    "entityType": "Pattern",
    "observations": [
      "Good pattern for large datasets",
      "Works better than offset",
      "Recommended approach"
    ]
  }]
})
// None of these help a future session make a decision

mcp__memory__create_entities({
  "entities": [{
    "name": "cursor-pagination",
    "entityType": "Pattern",
    "observations": [
      "Reduced p99 from 2s to 140ms on users table with 1.2M rows",
      "Offset pagination caused linear scan past row 100k; cursor uses indexed seek",
      "Implementation: ORDER BY id > :last_seen_id LIMIT :page_size"
    ]
  }]
})
// Each observation is independently actionable

mcp__memory__add_observations({
  "observations": [{
    "entityName": "offset-pagination",
    "contents": ["Bad for performance"]
  }]
})

mcp__memory__add_observations({
  "observations": [{
    "entityName": "offset-pagination",
    "contents": [
      "Caused 504 timeouts on /api/users?page=500 with 1M+ rows (OFFSET 500000 triggers sequential scan)"
    ]
  }]
})

# 1. Pagination patterns
pagination|cursor|offset|page|limit → pagination

# 2. Database patterns
database|sql|postgres|mysql|mongo|query|migration|alembic → database

# 3. Authentication patterns
auth|jwt|oauth|token|session|login|password → authentication

# 4. API patterns
api|endpoint|rest|graphql|grpc → api

# 5. Frontend patterns
react|vue|angular|component|frontend|ui|css|tailwind → frontend

# 6. Performance patterns
performance|slow|fast|cache|optimize|latency|throughput → performance

# 7. Architecture patterns
architecture|design|system|microservice|monolith → architecture

# 8. Pattern/Convention
pattern|convention|style|standard → pattern

# 9. Blockers/Issues
blocked|issue|bug|workaround|error|fix → blocker

# 10. Constraints
must|cannot|required|constraint|limitation → constraint

# 11. Default
<anything else> → decision

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

   Agent: {agent-id}

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

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

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

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)

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

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

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

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

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

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

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

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