claude-configs/skills/cognitive-memory/SCHEMA.md

Cognitive Memory Schema

Memory File Format

Each memory is a markdown file with YAML frontmatter. Filename format: {slugified-title}-{6char-uuid}.md

Example: graph/solutions/fixed-redis-connection-timeouts-a1b2c3.md

---
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
type: solution
title: "Fixed Redis connection timeouts"
tags: [redis, timeout, production, homelab]
importance: 0.8
confidence: 0.8
created: 2025-12-06T16:25:58+00:00
updated: 2025-12-06T16:25:58+00:00
relations:
  - target: def789ab-...
    type: SOLVES
    direction: outgoing
    strength: 0.8
    context: "Keepalive prevents idle disconnections"
---

Added socket_keepalive=True and socket_timeout=300 to Redis connection configuration.

Frontmatter Fields

Field	Type	Required	Description
id	string (UUID)	Yes	Unique identifier
type	string	Yes	Memory type (see below)
title	string (quoted)	Yes	Descriptive title
tags	list[string]	No	Categorization tags (inline YAML list)
importance	float 0.0-1.0	Yes	Importance score
confidence	float 0.0-1.0	No	Confidence score (default 0.8)
steps	list[string]	No	Ordered steps (procedure type only)
preconditions	list[string]	No	Required preconditions (procedure type only)
postconditions	list[string]	No	Expected postconditions (procedure type only)
created	string (ISO 8601)	Yes	Creation timestamp
updated	string (ISO 8601)	Yes	Last update timestamp
relations	list[Relation]	No	Relationships to other memories

Memory Types

Type	Directory	Description
solution	graph/solutions/	Fix or resolution to a problem
fix	graph/fixes/	Code-level fix or patch
decision	graph/decisions/	Architecture or design choice
configuration	graph/configurations/	Working configuration
problem	graph/problems/	Issue or challenge
workflow	graph/workflows/	Process or sequence
code_pattern	graph/code-patterns/	Reusable code pattern
error	graph/errors/	Specific error condition
general	graph/general/	General learning
procedure	graph/procedures/	Structured workflow with steps/preconditions/postconditions
insight	graph/insights/	Cross-cutting pattern from reflection cycles

Relation Fields

Field	Type	Required	Description
target	string (UUID)	Yes	Target memory ID
type	string	Yes	Relationship type
direction	string	Yes	outgoing or incoming
strength	float 0.0-1.0	No	Relationship strength
context	string (quoted)	No	Context description
edge_id	string (UUID)	No	Link to edge file for rich description

Relationship Types

SOLVES, CAUSES, BUILDS_ON, ALTERNATIVE_TO, REQUIRES, FOLLOWS, RELATED_TO

Edge File Format

Edge files live in graph/edges/ with full descriptions. Filename: {from-slug}--{TYPE}--{to-slug}-{6char}.md

---
id: <uuid>
type: SOLVES
from_id: <uuid>
from_title: "Fixed Redis connection timeouts"
to_id: <uuid>
to_title: "Redis connection drops under load"
strength: 0.8
created: <iso>
updated: <iso>
---

The keepalive fix directly resolves the idle disconnection problem because...

Edge frontmatter fields: id, type, from_id, from_title, to_id, to_title, strength, created, updated.

---

_index.json

Computed index for fast lookups. Rebuilt by reindex command. Source of truth: markdown files.

{
  "version": 2,
  "updated": "2025-12-13T10:30:00+00:00",
  "count": 313,
  "edges": {
    "<edge-uuid>": {
      "type": "SOLVES",
      "from_id": "<uuid>",
      "to_id": "<uuid>",
      "strength": 0.8,
      "path": "graph/edges/fixed-redis--SOLVES--redis-drops-a1b2c3.md"
    }
  },
  "entries": {
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": {
      "title": "Fixed Redis connection timeouts",
      "type": "solution",
      "tags": ["redis", "timeout", "production", "homelab"],
      "importance": 0.8,
      "confidence": 0.8,
      "created": "2025-12-06T16:25:58+00:00",
      "updated": "2025-12-06T16:25:58+00:00",
      "path": "graph/solutions/fixed-redis-connection-timeouts-a1b2c3.md",
      "relations": [
        {
          "target": "def789ab-...",
          "type": "SOLVES",
          "direction": "outgoing",
          "strength": 0.8,
          "context": "Keepalive prevents idle disconnections"
        }
      ]
    }
  }
}

Notes:

• _index.json is gitignored (derived data)
• Can be regenerated at any time with python client.py reindex
• Entries mirror frontmatter fields for fast search without opening files

---

_state.json

Mutable runtime state tracking access patterns and decay scores. Kept separate from frontmatter to avoid churning git history with access-count updates.

{
  "version": 1,
  "updated": "2025-12-13T10:30:00+00:00",
  "entries": {
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": {
      "access_count": 5,
      "last_accessed": "2025-12-13T10:15:00+00:00",
      "decay_score": 0.75
    }
  }
}

Notes:

• _state.json is gitignored (mutable, session-specific data)
• Access count increments on get operations
• Decay scores recalculated by python client.py decay

---

Episode File Format

Daily markdown files in episodes/ directory. Append-only, one file per day.

Filename format: YYYY-MM-DD.md

# 2025-12-13

## 10:30 - Fixed Discord bot reconnection
- **Type:** fix
- **Tags:** major-domo, discord, python
- **Memory:** [discord-bot-reconnection](../graph/fixes/discord-bot-reconnection-a1b2c3.md)
- **Summary:** Implemented exponential backoff for reconnections

## 11:15 - Chose websocket over polling
- **Type:** decision
- **Tags:** major-domo, architecture
- **Memory:** [websocket-over-polling](../graph/decisions/websocket-over-polling-d4e5f6.md)
- **Summary:** WebSocket provides lower latency for real-time game state updates

Notes:

• Episodes are chronological session logs
• Entries link back to graph memories when available
• Append-only (never edited, only appended)
• Useful for reflection and session review

---

CORE.md Format

Auto-generated summary of highest-relevance memories. Loaded into system prompt at session start.

# Memory Core (auto-generated)
> Last updated: 2025-12-13 | Active memories: 180/313 | Next refresh: daily (systemd timer)

## Critical Solutions
- [title](relative/path.md) (tag1, tag2)

## Active Decisions
- [title](relative/path.md) (tag1, tag2)

## Key Fixes
- [title](relative/path.md) (tag1, tag2)

## Configurations
- [title](relative/path.md) (tag1, tag2)

## Patterns & Workflows
- [title](relative/path.md) (tag1, tag2)

Notes:

• Budget: ~3K tokens (~12,000 chars)
• Regenerated by python client.py core
• Memories included based on decay_score (must be >= 0.2)
• Grouped by type category, sorted by decay score within each group
• Capped at 15 entries per section

---

Decay Model

decay_score = importance × e^(-λ × days_since_access) × log2(access_count + 1) × type_weight

Where:

• λ = 0.03 (half-life ~23 days)
• days_since_access = days since _state.json last_accessed
• access_count = from _state.json
• type_weight = per-type multiplier (see below)
• For access_count == 0, usage_factor = 0.5 (new memories start at half strength)

Type Weights

Type	Weight
procedure	1.4
decision	1.3
insight	1.25
solution	1.2
code_pattern	1.1
configuration	1.1
fix	1.0
workflow	1.0
problem	0.9
error	0.8
general	0.8

Thresholds

Range	Status
0.5+	Active
0.2-0.5	Fading
0.05-0.2	Dormant
<0.05	Archived

Vault

Pinned memories (in vault/) have a decay score of 999.0 (effectively infinite).

---

REFLECTION.md Format

Auto-generated summary of memory themes, cross-project patterns, and access statistics. Generated by python client.py reflection or automatically during reflect.

# Reflection Summary (auto-generated)
> Last updated: 2026-02-13 | Last reflection: 2026-02-13 | Total reflections: 2

## Themes
Top tag co-occurrences revealing recurring themes:

- **fix + python**: 52 memories ("Fix S3 upload...", "fix_cardpositions.py...")

## Cross-Project Patterns
Tags that span multiple projects:

- **fix**: appears in major-domo (38), vagabond-rpg (22), paper-dynasty (19)

## Most Accessed
Top 10 memories by access count:

1. [Title](graph/type/filename.md) - N accesses

## Recent Insights
Insight-type memories:

- [Title](graph/insights/filename.md) - content preview...

## Consolidation History

- Total merges performed: 0

Sections:

1. Themes - Top 8 tag co-occurrences with example memory titles (top 3)
2. Cross-Project Patterns - Tags spanning 2+ known projects with per-project counts
3. Most Accessed - Top 10 memories ranked by _state.json access_count
4. Recent Insights - Latest insight-type memories with 80-char content preview
5. Consolidation History - Merge count from episode files

Known projects: major-domo, paper-dynasty, homelab, vagabond-rpg, foundryvtt, strat-gameplay-webapp

---

_embeddings.json

Ollama embedding vectors for semantic search. Gitignored (derived, regenerated by python client.py embed).

{
  "model": "nomic-embed-text",
  "updated": "2026-02-13T12:00:00+00:00",
  "entries": {
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890": [0.0123, -0.0456, ...],
    ...
  }
}

Notes:

• Vectors generated from "{title}. {content_preview}" per memory
• Uses Ollama nomic-embed-text model at http://localhost:11434
• Batched in groups of 50, 300-second timeout for first-time model pull
• Falls back gracefully if Ollama is unavailable
• Must be refreshed after adding new memories (python client.py embed)

---

Procedure Memory Format

Procedure-type memories have additional frontmatter fields for structured steps:

---
id: a1b2c3d4-...
type: procedure
title: "Deploy Major Domo to production"
tags: [major-domo, deploy, docker]
importance: 0.8
confidence: 0.8
steps:
  - "Run tests"
  - "Build docker image"
  - "Push to registry"
  - "Deploy to LXC"
preconditions:
  - "All tests pass"
  - "On main branch"
postconditions:
  - "Service healthy"
  - "Discord bot online"
created: 2026-02-13T12:00:00+00:00
updated: 2026-02-13T12:00:00+00:00
---

Standard deploy workflow for the Major Domo Discord bot.

Notes:

• steps, preconditions, postconditions are optional lists
• Values are quoted YAML strings in the list
• Procedures have the highest decay weight (1.4) - they persist longest

---

_config.json

Embedding provider configuration. Gitignored (may contain API key).

{
  "embedding_provider": "ollama",
  "openai_api_key": null,
  "ollama_model": "nomic-embed-text",
  "openai_model": "text-embedding-3-small"
}

Notes:

• embedding_provider: "ollama" (default) or "openai"
• Provider changes trigger automatic re-embedding (dimension mismatch safety: ollama=768, openai=1536)
• Configure via: claude-memory config --provider openai --openai-key "sk-..."

---

.gitignore

_state.json
_index.json
_embeddings.json
_config.json

Only markdown files (memories, CORE.md, REFLECTION.md, episodes) are git-tracked. Index, state, embeddings, and config are derived/mutable data that can be regenerated.

---

Schema version: 3.0.0 | Created: 2026-02-13 | Updated: 2026-02-19