Remember - Store Decisions and Patterns

Filesystem vs MCP memory (Opus 4.7 guidance, CC 2.1.111+): Opus 4.7 is substantially better than 4.6 at reading filesystem memory across multi-session work. Use that to your advantage:

Short-lived handoff state (current phase, task in-progress, pending approvals) → .claude/chain/*.json files. Small, structured, session-scoped.

Durable auto-memory (user facts, feedback, project conventions) → ~/.claude/projects/<slug>/memory/*.md files with a one-line index in MEMORY.md. Read on every session start.

Cross-session knowledge graph (typed entities + relations for query traversal) → MCP memory server (this skill's default path). Best when future sessions will search for patterns.

The three are complementary, not alternatives. Prefer fs for anything you'd want to grep; prefer MCP for anything you'd want to traverse.

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

Argument Resolution

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

Architecture

The remember skill uses knowledge graph as storage:

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

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-6. Extract Entities and Create Graph

Extract entities (Technology, Agent, Pattern, Project, AntiPattern) from the text, detect relationship patterns ("X uses Y", "chose X over Y", etc.), then create entities and relations in the knowledge graph.

Load entity extraction rules, type assignment, relationship patterns, and graph creation examples: Read("${CLAUDE_SKILL_DIR}/references/graph-operations.md")

7. Confirm Storage

Display confirmation using the appropriate template (success, anti-pattern, or neutral) showing created entities, relations, and graph stats.

Load output templates and examples: Read("${CLAUDE_SKILL_DIR}/references/confirmation-templates.md")

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

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>"):

File	Content
`category-detection.md`	Auto-detection rules for categorizing memories (priority order)
`graph-operations.md`	Entity extraction, type assignment, relationship patterns, graph creation
`confirmation-templates.md`	Output templates (success, anti-pattern, neutral) and usage examples

Related Skills

ork:memory - Search, load, sync, visualize (read-side operations)

Error Handling

Knowledge graph unavailable → show configuration instructions
Empty text → ask user for content; text >2000 chars → truncate with notice
Both --success and --failed → ask user to clarify
Entity extraction fails → create generic Decision entity; relation fails → create entities first, retry

remember