---
id: 312bc25f-1d4c-4a17-8ea6-3516d9e952a2
type: solution
title: "Stdlib-only YAML frontmatter parsing for markdown memory files"
tags: [cognitive-memory, python, architecture, stdlib]
importance: 0.7
confidence: 0.8
created: "2026-02-13T17:39:51.592359+00:00"
updated: "2026-02-13T17:39:51.592359+00:00"
---

Built a complete YAML frontmatter parser/serializer using only Python stdlib (re module + manual parsing). Key design decisions:

- Parse frontmatter between --- markers with regex
- Handle nested lists (relations) and simple key-value pairs
- Slugify titles with 6-char UUID suffix for unique filenames
- Keep _index.json as derived cache (rebuilt from files via reindex)
- Keep _state.json for mutable data (access counts, decay scores) 
- Git-track markdown files but gitignore _index.json and _state.json

The decay model uses: importance × e^(-0.03 × days_since_access) × log2(access_count + 1) × type_weight
Half-life is ~23 days. Type weights range from 0.8 (error/general) to 1.3 (decision).

Content preview (first 200 chars) stored in _index.json enables zero-file-I/O search for recall and search commands.