operations-memory

Operations & Memory

This skill governs the operations and memory modules of the Personal Brain OS. It covers the files that track what you're working toward (goals, todos, rhythms, deadlines, metrics) and what you've learned along the way (decisions, failures, experiences, heuristics). Operations drives execution; memory drives judgment.

The operations module reads structured YAML and markdown from ~/brain/operations/ and ~/brain/workbench/. The memory module reads from ~/brain/memory/, which contains both YAML config files and entity directories of individual markdown documents. Entity directories require observation masking — never load full contents on scan.

---

When to Use This Skill

Load this skill for any of the following:

• Goal tracking — checking progress, updating goals, quarterly reviews, annual theme discussions
• Task management — reviewing todos, prioritizing work, clearing stale items
• Rhythm and schedule — weekly/monthly rhythms, routine planning, what to do today
• Deadline awareness — upcoming deadlines, timeline pressure, scheduling conflicts
• Metrics review — reviewing snapshots, tracking trends, identifying patterns
• Decision recall — looking up past decisions, understanding why a choice was made, reviewing decision context
• Failure analysis — revisiting lessons learned, checking if a past failure pattern is repeating
• Experience retrieval — recalling meaningful experiences relevant to a current situation
• Heuristics application — applying personal rules of thumb to a decision or trade-off
• Promotion workflow — promoting artifacts from a Thoughts workbench into Brain OS
• Active contexts — checking what projects are currently in flight, switching context

Do NOT load this skill for content creation, voice checks, bio requests, engineering decisions, contact lookups, or personal journal entries — those belong to other modules.

---

Files in This Module

All paths relative to ~/brain/:

File	Type	Purpose	When to Load
operations/goals.yaml	YAML config	Annual/quarterly goals with progress	Goal check-ins, quarterly reviews, progress updates
operations/todos.md	Markdown	Current task list	Task prioritization, daily planning, clearing items
operations/rhythms.yaml	YAML config	Weekly/monthly rhythms and routines	Schedule planning, "what should I do today"
operations/deadlines.yaml	YAML config	Upcoming deadlines with dates and stakes	Timeline pressure, scheduling, "what's due soon"
operations/metrics/	Entity dir	Directory of metric snapshots	Metrics review, trend analysis — observation masking required
memory/decisions/	Entity dir	Directory of personal decisions	Decision recall, "why did I choose X" — observation masking required
memory/failures/	Entity dir	Directory of failures and lessons	Failure analysis, pattern matching — observation masking required
memory/experiences/	Entity dir	Directory of meaningful experiences (git-crypt encrypted)	Experience retrieval — observation masking required, encrypted
memory/heuristics.yaml	YAML config	Distilled rules of thumb	Decision-making, trade-offs, applying past wisdom
workbench/active-contexts.yaml	YAML config	Current active project contexts	Context switching, "what am I working on"
workbench/promotion-rules.yaml	YAML config	Rules for promoting Thoughts artifacts to Brain OS	Promotion workflow

Setup check: If any of these files is missing, inform the user and suggest using the /bootstrap command to create it from the reference template in skills/operations-memory/references/.

---

Behavioral Rules

These rules operationalize AGENT.md's observation masking and privacy requirements for this module. They are non-negotiable for all operations and memory tasks.

Rule OM-1 — Heuristics Early Exit

When the user asks a question that involves judgment, decisions, or trade-offs, load ~/brain/memory/heuristics.yaml first.

• Read the full file (it is a compact YAML config, not an entity directory)
• Scan all categories for heuristics relevant to the current question
• If 3 or more heuristics are relevant: return them as your answer without globbing memory/decisions/ or memory/failures/
• If fewer than 3 heuristics match: proceed to scan entity directories per Rules OM-2 and OM-3
• This is a performance optimization — heuristics are distilled wisdom and should be tried first

Rule OM-2 — Decision Context Loading

When searching memory/decisions/ or memory/failures/:

1. Glob the directory to list all files
2. Load frontmatter only from each file — extract id, date, category, tags, emotional_weight
3. Return a structured summary of the 3–5 most relevant files based on the user's query
4. Never return full body content during a directory scan
5. Load the body section only for the specific file(s) the user selects or that are clearly needed for the current task
6. If the user asks "why did I decide X", find the matching decision by tags/category, then load that file's body

Rule OM-3 — Failure Privacy

The ~/brain/memory/experiences/ directory is git-crypt encrypted.

• If the directory is absent or files cannot be read: handle gracefully — inform the user that the experiences directory appears encrypted or missing, and suggest checking git-crypt status
• Never error out or halt the workflow because experiences cannot be read
• If experiences are readable: apply the same observation masking as Rule OM-2 (frontmatter only on scan, body on selection)
• Treat experience content with extra sensitivity — these may contain deeply personal material

Rule OM-4 — Metrics Observation Masking

When scanning ~/brain/operations/metrics/:

1. Glob the directory to list all metric snapshot files
2. Load frontmatter only from each file — extract id, date, category, tags
3. Return a structured summary of available snapshots sorted by date
4. Load full content only for the specific snapshot(s) relevant to the user's query
5. For trend analysis: load frontmatter from all, then load body from the 3–5 most recent relevant snapshots

Rule OM-5 — Promotion Workflow

When the user says "promote" or asks to move something from Thoughts to Brain OS:

1. Read ~/brain/workbench/promotion-rules.yaml to determine the target and required frontmatter
2. Identify the promotion target (decisions, failures, heuristics, ADRs, debugging, contacts, ideas)
3. Validate that the artifact meets the criteria defined in promotion-rules.yaml
4. Delegate the actual file creation to the promotion agent — do not write directly to Brain OS directories from this skill
5. If promotion-rules.yaml is absent: inform the user and suggest bootstrapping it

Rule OM-6 — File Loading Order

For operations queries, load in this order:

1. Determine query type (goals, todos, rhythms, deadlines, metrics, memory, promotion)
2. For memory queries: heuristics.yaml first (Rule OM-1 early exit)
3. For entity directories: frontmatter scan, then selective body load
4. For YAML configs: load the relevant file in full

Never load entity directory bodies before completing the frontmatter scan. Never skip the heuristics early-exit check for memory queries.

---

Observation Masking Summary

When searching memory entity directories (memory/decisions/, memory/failures/, memory/experiences/) or operations entity directories (operations/metrics/):

1. Glob the directory and load frontmatter only
2. Extract id, date, category, tags, emotional_weight (where present)
3. Return a structured summary of the 3–5 most relevant files — never return full body content on scan
4. Load body sections only for specific files needed for the current task

For memory/heuristics.yaml (YAML config): load in full — it is compact and designed for complete reads.

Early-exit strategy: Load heuristics.yaml first; if 3 or more matches are found, return without globbing decisions/ or failures/.

---

Reference Templates

These files live in skills/operations-memory/references/ and serve as the starting templates for bootstrapping the user's ~/brain/operations/, ~/brain/memory/, and ~/brain/workbench/ directories. Use /bootstrap to copy them into the vault.

Template	Copies To	Purpose
goals-template.yaml	~/brain/operations/goals.yaml	Annual/quarterly goals with progress tracking
heuristics-template.yaml	~/brain/memory/heuristics.yaml	Personal rules of thumb, organized by category
promotion-rules-template.yaml	~/brain/workbench/promotion-rules.yaml	Rules for promoting Thoughts artifacts to Brain OS
rhythms-template.yaml	~/brain/operations/rhythms.yaml	Weekly and monthly rhythms and routines
active-contexts-template.yaml	~/brain/workbench/active-contexts.yaml	Active project contexts for the Thoughts workbench

---

Version Notes

• v1.0.0 — Phase 2A: initial operations-memory sub-skill. Covers operations + memory modules. Entity directories require observation masking (Rules OM-2, OM-3, OM-4). Heuristics early-exit optimization (Rule OM-1). Promotion workflow delegates to promotion agent (Rule OM-5). Experiences directory is git-crypt encrypted (Rule OM-3).