SuperAPI AI Directory

memory-management

General & other

View repository

Updated 10-16 07:18

About this skill

Memory Management

Memory File Format

Frontmatter schema (simple key: value, NOT general YAML):

---
name: <string, required>           # short identifier
description: <string, required>    # one-line summary for relevance matching
type: <enum, required>             # value | user | feedback | project | reference
---
  • All values are plain strings, no quoting needed unless value contains :
  • No nested structures, no lists, no multi-line values
  • Body follows after the closing --- delimiter as markdown

MEMORY.md Index Format

  • Plain markdown file, no frontmatter
  • Contains links to individual memory files with brief descriptions
  • Lines after 200 are truncated by Claude Code's loader — keep concise
  • Entry format: - [filename.md](filename.md) — brief description
  • When writing: create individual .md file first, then append entry

Staleness Scoring

Exponential decay: score = 100 * (1 - exp(-age_days * ln(2) / half_life))

Type Half-life Score 50 at Score 90 at
value 365 days 365d ~1213d
user 180 days 180d ~598d
feedback 90 days 90d ~299d
reference 60 days 60d ~199d
project 14 days 14d ~47d
unknown 30 days 30d ~100d

Score-to-action: 0-50 = keep, 50-75 = review, 75-100 = prune.

Deep verification modifiers (additive, capped at 100):

  • +20 if referenced file is missing
  • +30 if referenced function/class not found
  • +10 if URL returns non-200
  • +15 if referenced branch doesn't exist

Claim Extraction Heuristics (Deep Audit)

Claim Type Detection Pattern Verification
File path Contains /, ends with file extension Glob for existence
Function/class Backtick identifier in camelCase/PascalCase/snake_case Grep in project
URL Starts with http:// or https:// curl HEAD request
Branch After "branch" keyword or git pattern in backticks git branch -a
Package In dependency/package context Grep in manifest files

Skip generic descriptions that aren't verifiable (e.g., "use a database" vs "uses PostgreSQL 15").

Destination Routing

Destination When to Use Target Path
Memory file (value) Learned value choices — "X is better than Y" Session's project memory/ dir, type=value
Memory file Knowledge for Claude's future behavior Session's project memory/ dir
CLAUDE.md High-impact instructions for every conversation Session's project root CLAUDE.md
Knowledge file Human-readable notes, decision logs docs/knowledge/ in project root
Skip Session-specific, not worth preserving —

Priority: Value choices are the most durable memories. When extracting, surface them first. Facts decay (files move, APIs change); values persist (readability > cleverness survives any rewrite).

Rule: Always target the session's originating project, not the current shell cwd.

Mutation Rules

Layout How to Write
Index + files Create .md file with frontmatter, append to MEMORY.md
Standalone MEMORY.md Convert to index layout: create first .md file, rewrite MEMORY.md as index
No memory dir Create memory/, create MEMORY.md, create .md file
Malformed frontmatter Read as type=unknown. Never corrupt existing files.

Archive Convention

  • Location: memory/archive/ subdirectory
  • Files preserved intact (frontmatter + content)
  • MEMORY.md entry removed on archive
  • iter_memories() skips archive/ — invisible to dashboard/audit/tokens
  • Standalone MEMORY.md: archiving not supported (offer delete or keep)
  • Restore: manual move from archive/ + re-add to MEMORY.md