Memory System

You are managing Claude's persistent memory system. All data lives in a single JSONL file (one JSON object per line):

<skill-dir>/mem.jsonl

where <skill-dir> is the directory containing this SKILL.md file. This file is the only source of truth.

Line Format

Each line in mem.jsonl is a self-contained JSON object:

{"id":"mem_a1b2c3d4","topic":"Prefer Bun over Node","category":"preferences","content":"Always prefer Bun over Node as the default JS/TS runtime and package manager","tags":["bun","node","runtime"],"priority":"high","created":"2026-03-11","updated":"2026-03-11","source":"user","project":"global"}

Fields:

• id: mem_ + 8 hex chars. Must be unique.
• topic: Short descriptive title.
• category: preferences|architecture|debugging|projects|tools|people|decisions|workflows|integrations|performance|security|testing|documentation|deployment|general
• content: The full memory — descriptive and self-contained. This is the primary search target.
• tags: 2-4 relevant keywords.
• priority: normal (default), high (user says "important"/"always"/"never"), critical (user says "critical"/"essential").
• source: user (explicitly asked) or auto (inferred).
• project: Project name or global.

Why JSONL

• Save = append: Adding a memory is a single line append — no need to read/parse/rewrite the whole file.
• Grep-native: Each line is self-contained, so grep finds matches instantly.
• Human-readable: Open the file and each line is one memory.
• No desync: Single file, no index to keep in sync.

Commands

Parse $ARGUMENTS to determine which command to run.

save <topic> [: <content>]

1. Read mem.jsonl (create the file if missing — start empty).
2. Check for duplicates — use Grep on the file to find similar topics or content. If found, ask user whether to update or create new.
3. Auto-categorize using the rules below. If ambiguous, ask.
4. Infer priority from language.
5. Auto-generate 2-4 tags.
6. If the user gave inline content after :, use that. Otherwise, compose from topic and conversation context.
7. Run: bun <skill-dir>/scripts/save.ts --topic=<topic> --content=<content> --category=<category> [--tags=<t1,t2,...>] [--priority=<level>] [--source=<source>] [--project=<project>]
8. Display the output to confirm the save.

To update an existing memory: read the full file, replace the matching line, write back. This is the only operation that rewrites the file besides forget.

search <query>

Run: bun <skill-dir>/scripts/search.ts <query>

Display the output directly to the user. If no results, suggest alternative search terms.

list [category] [--priority=<level>] [--tag=<tag>]

Run: bun <skill-dir>/scripts/list.ts [category] [--priority=<level>] [--tag=<tag>]

Display the output directly to the user.

forget <topic-or-id>

1. Run bun <skill-dir>/scripts/search.ts <topic-or-id> to find matches.
2. If multiple matches, show them and ask the user to pick.
3. Show the full memory and ask for confirmation.
4. Read mem.jsonl, remove the matching line, write back.
5. Confirm deletion.

status

Run: bun <skill-dir>/scripts/status.ts

Display the output directly to the user.

Auto-Categorization Rules

• preferences: "prefer", "always use", "never", "default to", "style", "convention", "habit", "rule", "standard", "guideline", "opinionated"
• architecture: "pattern", "structure", "architecture", "design", "component", "module", "API", "abstraction", "layer", "boundary", "interface", "schema", "model", "entity", "relationship", "dependency", "monorepo", "microservice"
• debugging: "fix", "bug", "error", "issue", "workaround", "solution", "crash", "stack trace", "exception", "regression", "flaky", "race condition", "deadlock", "memory leak", "segfault"
• projects: project names, repo refs, "codebase", specific tech stack, "milestone", "roadmap", "sprint", "backlog", "scope", "deadline", "stakeholder"
• tools: tool names, "config", "setup", "install", CLI references, "plugin", "extension", "linter", "formatter", "bundler", "compiler", "transpiler", "package manager", "IDE", "editor"
• people: names, "team", "contact", "owner", "maintainer", "reviewer", "lead", "oncall", "contributor", "stakeholder", "manager"
• decisions: "decided", "chose", "rationale", "trade-off", "why we", "ADR", "RFC", "pros and cons", "alternative", "rejected", "approved", "consensus"
• workflows: "workflow", "process", "pipeline", "CI", "CD", "step", "automation", "hook", "pre-commit", "post-merge", "cron", "scheduled", "trigger", "approval", "gate"
• integrations: "integration", "webhook", "third-party", "API key", "service", "connect", "OAuth", "SSO", "SDK", "endpoint", "callback", "event", "subscription", "sync"
• performance: "performance", "latency", "speed", "optimize", "cache", "memory usage", "profiling", "benchmark", "bottleneck", "throughput", "cold start", "lazy load", "bundle size", "tree shaking"
• security: "security", "auth", "permission", "vulnerability", "secret", "encrypt", "CORS", "CSP", "XSS", "CSRF", "injection", "sanitize", "token", "certificate", "firewall", "audit"
• testing: "test", "spec", "coverage", "mock", "fixture", "assertion", "TDD", "e2e", "unit test", "integration test", "snapshot", "stub", "spy", "regression test", "smoke test", "flaky test"
• documentation: "docs", "readme", "comment", "JSDoc", "changelog", "wiki", "API docs", "tutorial", "example", "migration guide", "runbook", "playbook", "onboarding"
• deployment: "deploy", "release", "staging", "production", "Docker", "infrastructure", "Kubernetes", "rollback", "canary", "blue-green", "feature flag", "env variable", "secrets manager", "CDN", "load balancer"
• general: fallback

If content spans categories, pick the primary one and add the secondary as a tag.

Important Behaviors

• Appends are fast — for save, just append a line. Only rewrite on update/forget.
• Create the file if it doesn't exist — never error on missing structure.
• Be concise: confirm saves briefly, warn about duplicates.
• If no arguments provided, show the help menu below.
• Use the current date from the system for timestamps.
• Never auto-delete — always ask the user first.

Help Output (no arguments)

Memory System — Persistent knowledge management

Commands:
  /mem save <topic>              Save a memory (interactive)
  /mem save <topic>: <content>   Save with inline content
  /mem search <query>            Search all memories
  /mem list [category]           List memories (optional filter)
  /mem list --priority=high      Filter by priority
  /mem list --tag=<tag>          Filter by tag
  /mem forget <topic-or-id>      Remove a memory
  /mem status                    Stats overview

Examples:
  /mem save always use bun instead of npm
  /mem save auth-pattern: We use JWT with refresh tokens in httpOnly cookies
  /mem search authentication
  /mem list debugging --priority=high
  /mem forget mem_a1b2c3d4
  /mem status

Priority is auto-detected, or specify:
  /mem save [critical] never commit .env files