A Tiered Memory System and documentation governance framework for AI coding agents, featuring standardized templates, Git-based staleness detection, and Guardian semantic validation to ensure consistency and freshness of project knowledge.
Overview#
Cortex TMS (Tiered Memory System) is a documentation governance framework designed for AI coding agents. It addresses core pain points in AI-assisted development through three pillars:
- π Consistency: Generate AI-readable governance document templates including
PATTERNS.md(code patterns),CLAUDE.md(agent workflow rules),ARCHITECTURE.md(system design),DOMAIN-LOGIC.md(business rules) - π Freshness Detection: Git-based document staleness detection, comparing document modification dates vs code commit activity with configurable thresholds (days + commit count)
- π‘οΈ Safety Supervision:
CLAUDE.mdgovernance rules require human approval for critical operations, Git commit/push requires approval
Core Capabilities#
CLI Commands#
| Command | Function |
|---|---|
cortex-tms init | Interactive scaffolding to initialize document structure |
cortex-tms validate | Validate project TMS health status (including staleness detection) |
cortex-tms status | Text summary: project health + Sprint progress |
cortex-tms dashboard | Full-screen interactive terminal UI (v4.0 new) |
cortex-tms review | Guardian: AI-driven semantic validation |
cortex-tms hooks | Manage Git hooks (pre-commit validation) |
Guardian Semantic Validation#
- Zod-based semantic validation
- Safe Mode: read-only analysis, β₯80% confidence
- Captures pattern drift that grep cannot detect
- Uses user's own OpenAI/Anthropic API Key
Tiered Documentation System#
| Tier | File | Purpose |
|---|---|---|
| HOT | NEXT-TASKS.md | Active Sprint and current focus |
| HOT | CLAUDE.md | CLI commands & workflow configuration |
| WARM | docs/core/ARCHITECTURE.md | System design & tech stack |
| WARM | docs/core/PATTERNS.md | Canonical code examples |
| COLD | docs/archive/ | Historical changelog |
Quick Start#
# Initialize governance documents
npx cortex-tms@latest init
# Validate document health
npx cortex-tms@latest validate
# Strict mode (for CI)
npx cortex-tms@latest validate --strict
Configuration Example#
{
"version": "4.0.0",
"staleness": {
"enabled": true,
"thresholdDays": 30,
"minCommits": 3,
"docs": {
"docs/core/PATTERNS.md": ["src/"]
}
}
}
Use Cases#
- β Multi-file complex projects
- β Team collaboration projects
- β Long-term maintenance projects
- β AI-intensive workflows (Claude Code / Cursor / Copilot)
Requirements#
- Node.js β₯ 18.0.0
- Git (for staleness detection)