| name | memory-bank |
| description | Schema definitions and validation rules for the persistent memory system. Defines directory structure, frontmatter contracts, JSONC graph schema, entity registry format, deduplication keys, and operation modes. Agents reference this skill for structural contracts — operational procedures live in agent definitions (curator, historian). |
| argument-hint | mode=bootstrap|retrieve|update|reconcile; task=<goal>; project=<slug optional> |
| user-invocable | true |
| metadata | {"created_at":"2026-03-25T02:10:07.1689810Z","updated_at":"2026-04-14T23:10:00Z"} |
Memory Bank — Schema & Contracts
Canonical reference for the memory system's data structures. Agents consult this skill for what the data looks like, not how to operate on it:
- Curator → owns wiki operations (ingest, query, lint, synthesize)
- Historian → owns memory persistence (sessions, plans, executions, log appends)
- This skill → owns schema contracts, validation rules, and operation modes
Auditability and Time Source
- Fetch canonical UTC time from the source defined in
project-context skill (defaults to system clock UTC).
- If the configured time source is unavailable, abort write operations and return a recoverable error.
- Every memory file name must start with the normalized prefix:
YYYY-MM-DDTHH-MM-SSZ.
- Normalization:
2026-03-24T22:40:05 → 2026-03-24T22-40-05Z.
Record Metadata Contract
All auditable markdown memory files must start with:
---
created_at: '<canonical UTC time>'
updated_at: '<canonical UTC time>'
utc_datetime_prefix: '<YYYY-MM-DDTHH-MM-SSZ>'
---
- For new files:
created_at = updated_at = time.
- For updates: preserve
created_at, refresh updated_at.
Memory Directory Structure
.memories/
├── raw/ # Immutable source documents — NEVER modified
│ └── assets/ # Images and binaries from sources
├── wiki/ # LLM-compiled knowledge (owned by curator)
│ ├── entities/ # One page per canonical entity
│ ├── concepts/ # Thematic and conceptual pages
│ ├── sources/ # Summary page for each ingested source
│ └── synthesis/ # Cross-cutting analyses, filed-back queries
├── infrastructure/ # Pipeline design records
│ └── decisions/ # ADRs about agents, hooks, conventions
├── sessions/ # Session records and timelines
├── plans/ # Implementation plans
├── executions/ # Execution reports
├── errors/ # Error logs
├── architecture/decisions/ # Project ADRs
├── agents/handoffs/ # Subagent handoff records
├── context/ # Knowledge graph and context files
│ ├── knowledge-graph.index.jsonc
│ └── entity-registry.jsonc
├── index.md # Discoverable record catalog (by category)
└── log.md # Append-only chronological operation timeline
File naming: <utc_datetime_prefix>__<intention-revealing-name>.md
Naming Standard
- Use intention-revealing names:
taskExecutionSummary not result, dependencyRelation not link.
- Avoid ambiguous names:
data, info, temp, item, unknown.
- Keep naming consistent across markdown records and JSONC graph fields.
Entity Registry Schema
File: .memories/context/entity-registry.jsonc
{
"registryGeneratedAtUtc": "2026-03-24T22:40:05Z",
"entries": [
{
"canonicalName": "orchestrator",
"aliases": ["nexus-orchestrator", "main-orchestrator"],
"entityType": "service"
}
]
}
Resolution rules:
canonicalKey = entry.canonicalName.trim().toLowerCase()aliasKey = alias.trim().toLowerCase()- Before adding an entity, check if its normalized name matches any canonicalKey or aliasKey.
- If matched → use the canonical name. If not → add and register.
Knowledge Graph Schema
File: .memories/context/knowledge-graph.index.jsonc
{
"graphGeneratedAtUtc": "2026-03-24T22:40:05Z",
"entities": [
{
"entityName": "orchestrator",
"entityType": "service",
"observations": ["Coordinates thinker, planner, executor, historian"]
}
],
"relations": [
{
"sourceEntityName": "orchestrator",
"targetEntityName": "planner",
"relationType": "delegates_to"
}
]
}
Deterministic Deduplication Keys
- Entity:
entityName.trim().toLowerCase()
- Relation:
source|relationType|target (all trimmed, lowercased)
- Observation:
entityName|observationText (trimmed)
- Keep first-seen on collision. Sort entities by name, relations by source→type→target, observations lexicographically.
JSONC Validation
Required top-level keys: graphGeneratedAtUtc, entities, relations.
Reject records with non-meaningful names (empty, data, info, temp, item, unknown).
Write atomically: temp file → re-parse → replace target.
Operation Modes
bootstrap
Create missing core tree. Initialize empty knowledge-graph.index.jsonc. Register files in index.md.
retrieve
Read in order: index.md → context/project.md → latest session → relevant plans/executions → knowledge graph.
Build a retrieval packet with: relevant entities/relations, top observations, prior decisions, known failure preventions.
update
Persist new memory. Enforce metadata policy (immutable created_at, refresh updated_at). Apply deduplication. Update index.md last.
reconcile
Validate consistency between records and graph. Mark stale/conflicting facts as superseded (never silently remove). Emit health summary.
Quality Gates
Before closing any memory cycle:
Nexus Integration
orchestrator: calls retrieve before first planning, update after execution.historian: owns file persistence and index maintenance. Consult this skill for schema contracts.curator: owns wiki operations. Consult this skill for frontmatter and JSONC contracts.thinker: consumes retrieval packet to reduce ambiguity.planner: references decisions, constraints, and linked failures.executor: writes execution outcomes for subsequent memory updates.
Output Contract
## Memory Operation
- mode: <bootstrap|retrieve|update|reconcile>
- project: <slug>
- status: <success|partial|failed>
- memory_write_timestamp_utc: <canonical UTC>
- utc_datetime_prefix: <YYYY-MM-DDTHH-MM-SSZ>
## Retrieved or Updated Artifacts
- <path>: <why it matters>
## Graph Delta
- entities_added_count: <count>
- relations_added_count: <count>
- observations_added_count: <count>
- superseded_records_count: <count>
## Memory Health
- index_synced: <yes|no>
- consistency_warnings: <none|list>
