# CortexGraph: Memory System Architecture and Development CortexGraph is the memory infrastructure underlying the cognitive architecture projects, most notably [[Cognition/Tattooed Ralph Loop]]. ## Hybrid Storage Architecture A key architectural decision (December 2025) adopted a hybrid storage approach: - **JSONL/Markdown files** remain the canonical source of truth (human-readable, git-friendly, inspectable) - **SQLite** serves as a derived index layer with graph capabilities (recursive CTEs) and vector search (sqlite-vec extension) The guiding principle: **"Index is derived, source is canonical."** ## Storage Evolution - SQLite added in v0.7.5 as an alternative backend for short-term memory (STM) only - JSONL remains the default - Long-term memory (LTM) continues to use Markdown files in an Obsidian vault ## Constitutional Alignment A Constitutional Alignment system was proposed for memory management, decoupling: - The **Learning Mechanism** (LLM/Neocortex) from - The **Value System** (Constitution/Limbic System) The constitution acts as a neuromodulatory and gating layer for memory consolidation. ## Development Lessons - Always run ruff format locally before commits - Always update test mocks in the same commit as implementation changes - Never get stuck in whitespace formatting loops - Test suite refactoring identified 35% reduction potential across 6 test files (13,221 → 8,500 lines) For effective retrieval from CortexGraph, see Memory Search Practices. ## Related Notes - [[Cognition/Tattooed Ralph Loop]] — the bio-mimetic cognitive architecture that uses CortexGraph for memory persistence - [[AI-Behavior/Context Loss Mitigation]] — academic synthesis of the memory architecture patterns CortexGraph implements (MemGPT, Graphiti, hierarchical memory) - [[eFIT/Ebbinghaus Pruning]] — the forgetting curve model used by CortexGraph's strategic decay mechanisms - Memory Search Practices — best practices for searching and retrieving memories from the CortexGraph system --- *Atomic note derived from CortexGraph memories*