Provides domain instructions for knowledge capture, persistence, and maintenance in the Personal Knowledge Base (PKB) ($ACA_DATA).
Immediate Mode (/remember)
Invariants
Do not use Write or Edit on files under $ACA_DATA/. Use the PKB MCP toolset.
Use mcp_pkb_search for semantic discovery. Do not use Glob or Grep on $ACA_DATA/.
Hard Rules
mcp_pkb_create: Create a document (projects, contexts, meeting notes).
mcp_pkb_create_memory: Add a memory/note.
mcp_pkb_append: Extend an existing document.
mcp_pkb_get_document: Read a document.
mcp_pkb_search: Search before creating new content — and before asserting a fact. Don't assume; look it up.
Curation
Capture episodic records accurately in the moment.
Curate and synthesize knowledge inline as decisions or patterns emerge; do not defer all synthesis to the /sleep loop.
Storage Hierarchy
Content
Write Via
Target Location
Epics/projects
mcp_pkb_create(type="epic"|"project")
projects/
Tasks/issues
gh issue create (GitHub primary)
Synced automatically
Durable knowledge
mcp_pkb_create or mcp_pkb_create_memory
knowledge/, context/
Session findings
mcp_pkb_update_task on parent task
Task body
Axioms / framework rules
Invoke /framework skill — do NOT write to brain/context/
skills/ via framework workflow
File Locations
Content
Location
Notes
Project metadata
projects/<name>.md
Hub files. Hub-doc type is epic.
Project details
projects/<name>/
Subdirectory.
Goals
goals/
Strategic objectives.
Context (about user)
context/
User preferences, history.
Sessions/daily
sessions/
Daily notes only, type: daily-note.
General knowledge
knowledge/<topic>/
Durable facts (non-user).
Meeting/call notes
knowledge/<topic>/ or projects/
type: meeting-note.
Maps of Content (MOCs)
knowledge/ or topic subdirs
Navigational hubs, type: moc.
Episodic Classification
Operational episodic (agent activity, debugging logs, experimental steps) -> Update parent task body using tasks MCP tools. Do not create new documents in $ACA_DATA/.
Durable episodic (meeting notes, user daily notes) -> Save to $ACA_DATA/ with correct type frontmatter.
Canonical Topic Notes (Enduring Memory)
Maintain exactly one canonical note per first-class topic (tools, projects, skills, agents, concepts).
Update existing topic notes using mcp_pkb_append in the relevant section.
Create new canonical notes with a standard section scaffold (e.g., Overview, Usage, Known Issues) only if the topic does not exist.
Avoid creating one-off observation files.
Reconciliation
During updates, search for duplicate or peer notes. Merge unique content, retire weaker versions, and update wikilinks. For how to retire — delete the superseded file and trust git history; do not leave superseded_by: pointers — follow the single canonical rule in [[consolidation-procedure]] Step 3.
Wikilink Conventions: Add wikilinks only in prose. Never put them inside code blocks, inline code, or technical tables. Do not create a standalone "See Also" section.
Abstraction Level
For framework tasks, capture generalizable patterns (e.g., "Configuration should be set once at initialization") rather than local implementation details.
Observation Notation
Factual claims in episodic notes must be formatted as Obsidian callouts:
If prior cycles ran in this session -> short-loop.
Default -> full-session.
Maintenance Phases
See [[references/maintenance-phases]] for detailed sub-agent rules, pacing, and exit protocols.
Phase
Name
0
Graph Health Baseline
1
Session Backfill
2
Transcript Mining
3
Episode Replay
4
Knowledge Consolidation
5
Index Refresh
6
Data Quality Reconciliation
7
Staleness Sweep
8
Refile Processing
9
Graph Maintenance
10
Consolidation Self-Check
11
Brain Sync
CI Environment Constraints
When running on GitHub Actions, no PKB MCP server is available. Direct file tool operations (Bash, Glob, Grep, Read, Write, Edit) on markdown files are allowed. Do not edit files outside $AOPS_SESSIONS/ (except git commits/push).
