session-context

name	session-context
description	Session context persistence for project goals, decisions, progress, and gotchas; use when restoring project state, managing session notes, or checking whether context was injected at startup.
user-invocable	false
version	1.0.0

Session Context Persistence

Overview

Per-project context lives in $CLAUDE_PLUGIN_DATA/openltm.db (SQLite). Hooks manage it automatically. Project names come from ~/.claude/projects/registry.json — run /openltm:project register to see yours.

Claude does NOT manually write context files. Hooks handle all reads and writes.

The 4 Context Types

Type	Purpose	Managed by
goal	Current objective (1-3 lines)	/openltm:project init to seed; auto-replaced on change
decision	Architectural / key choices	Permanent — never trimmed
progress	Session log — what was done	UpdateContext hook at session end; trimmed to last 20
gotcha	Warnings, pitfalls, blockers	Permanent — never trimmed

What Happens at Session Start

The SessionStart hook:

1. Resolves project from registry.json
2. Regenerates context-summary.md from DB
3. Injects up to 60 lines of context into your session
4. If DB has LTM memories: also injects importance-5 globals + top-15 project memories

You'll see ## Restored Project Context at session start when this fires. Acknowledge it briefly and confirm you're ready to continue.

LTM Commands (store and search learned insights)

Command	When to use
/openltm:memory learn	After discovering a non-obvious pattern, gotcha, or decision
/openltm:memory recall [query]	Before starting work on a topic — surface past decisions
/openltm:memory forget <id>	When a memory is wrong or stale
/openltm:memory relate <src> <tgt> <type>	Link two related memories

Recall before a non-trivial problem to check for prior knowledge; skip it for trivial one-liners.

What PreCompact Does

When compaction fires, PreCompact hook:

1. Reads DB for all 4 context types for this project
2. Writes context-summary.md (max ~60 lines) as a human-readable fallback
3. This file is injected at the next SessionStart

You do not manage context-summary.md — the hook overwrites it each compaction.

Short-Term vs Long-Term Memory

Question	Answer	Store as
Specific to the current project?	Yes	context_item (hooks auto-manage)
Useful in ALL future projects?	Yes	/openltm:memory learn (global memories table)
Temporary note / work log?	Yes	context_item progress
Permanent rule, gotcha, or decision?	Yes	/openltm:memory learn --importance 5

Short-term = context_items. Auto-managed by hooks. Expires after 14 days inactivity. Long-term = memories. Persist forever. Inject into every session via SessionStart.

When to promote: If a project-level gotcha has burned you twice, promote it to global LTM with /openltm:memory learn --importance 5.

Promoting Patterns to Durable LTM

Gotchas and decisions in context_items survive until the project is stale (14 days inactive). For lessons that must persist across all projects permanently, use /openltm:memory learn with importance=5:

/openltm:memory learn "Supabase RLS must be enabled before production" --category gotcha --importance 5

These appear in the memories table and inject into every session regardless of project.

Rules

• Never manually write to context-goals.md, context-decisions.md, context-progress.md, or context-gotchas.md
• Never manually edit context-summary.md — it is auto-generated
• Use /openltm:memory learn to persist important insights to global LTM
• Use /openltm:memory recall before starting non-trivial tasks
• Use /openltm:project init to seed a new project goal (not to create .md files)
• If context wasn't injected at session start, run /openltm:health to diagnose