Cross-Session Memory Plugin

A full-stack memory and context management system for AI coding assistants. Persists knowledge across sessions, compacts context on the fly, checkpoints progress, and auto-documents your codebase, all backed by PostgreSQL and pgvector.

What It Does

This plugin gives an AI assistant long-term memory. Without it, every new session starts from zero. With it, the assistant remembers what it did last session, what decisions were made, what went wrong, what the codebase looks like, and where it left off.

Memory System

• Cross-session persistence - Memories are stored in PostgreSQL and survive session restarts. Every session can recall, search, and build on knowledge from prior sessions.
• Host-neutral bridge path - The Postgres memory core can now be reached from OpenCode or from the Codex bridge export without rewriting MemoryManager.
• Automatic memory extraction - After every assistant turn, raw conversation text is distilled into structured semantic memories with no user effort.
• Memory types - conversation, workspace, repo, preference, lesson, episodic, and procedural.
• Hybrid search - Queries use Reciprocal Rank Fusion across vector similarity, full-text search, and entity matching.
• Explicit recall telemetry - Search, list, and context recall write memory_recall_events rows with hashed queries only. No raw query text is stored by default.
• Concept extraction and knowledge graph - Concepts are extracted from memory content and linked together for entity-aware recall.
• Prune scoring - Dry-run prune scoring now accounts for recall frequency so old but frequently used memories stay protected.
• Manual embedding backfill - Legacy rows with embedding IS NULL can be repaired explicitly through runtime/API backfill. This never runs automatically on startup.

Context Pipeline

• Context compilation - Builds a token-budgeted manifest from recent work, goals, lessons, and project context.
• Codex context brief - CodexMemoryBridge.getContextBrief({ projectRoot, task }) builds a compact brief plus lesson/risk recall before a fresh Codex task burns context rediscovering the repo.
• Tool-call distillation - Converts raw tool output into structured summaries and references.
• Assistant text compaction - Compresses long assistant text while preserving important lines.
• Compaction quality gate - Rejects unsafe compactions instead of silently dropping signal.
• Context rollover - Generates a continuation brief when prompt pressure gets too high.

Checkpoint System

• Session checkpoints - Snapshots current work into durable PostgreSQL-backed checkpoints.
• Auto-checkpointing - Queues checkpoints before risky operations.
• Checkpoint markdown - Renders checkpoints into readable summaries for debugging and handoff.

Behavioral Growth Tracking (Phase 30)

• Memory → behavior change - Tracks whether recalled lessons/memories actually change agent behavior across sessions.
• 7 growth categories: loop_prevention, schema_lesson_application, boundary_adherence, causal_depth_improvement, repo_fact_reuse, drift_correction, hydration_depth_improvement.
• Growth metrics: event count, category breakdown, baseline comparison, overall growth score.
• Proof target: "The system grows from what it remembers" — not just "the system remembers."

Response Mode Selector (Phase 29)

• Adaptive depth - Auto-selects 'basic' (boundary-only) or 'deep' (boundary + evidence + causal chain + narrative arc) based on available hydration context.
• Drivers: record count, thread presence, phase narrative, user hints ('deep', 'narrative', 'why', 'how')
• Graceful fallback — deep mode degrades to basic when context insufficient.

Value Source Guard (Phase 28)

• Known vs inferred values - Distinguishes explicitly stored user preferences from values inferred from the project arc. Prevents self-models from treating inferences as confirmed facts.
• Classification - classifyValueClaim, guardValueSources, detectUnlabeledInferences. Tags each value claim with source ('known' | 'inferred'), evidence, and confidence.

Phase Narrative Builder (Phase 27)

• Causal chain reconstruction - Connects phases 21-26 into a narrative: problem → action → result → downstream change. Turns index-card continuity into narrative continuity.
• Causation anchors - Uses real A/D/E experiment results as fixtures. Session D proved silent recall → Phase 22 drift tracking → Phase 23 evidence hydration → Phase 24 causal threads → Phase 25 depth scoring → Phase 26 integration.
• Gap detection - Reports missing links in the chain instead of hallucinating causation.
• Token budget - Respects max token limit for context injection.

Self-Continuity Integration (Phase 26)

• Unified injection path - Wires causal thread hydration into self-continuity record injection, so context compilation automatically includes the "why" behind each record.
• Two hydrators as one - SelfContinuityIntegration combines SelfContinuityHydrator (canonical fields) and CausalThreadHydrator (problem/action/result chains) into a single call.
• Graceful degradation - Thread hydration failure falls back to record-only hydration; never blocks normal recall.
• Dependency injection - Accepts hydrator instances for testability.

Hydration Depth Scoring (Phase 25)

• Depth vs stability - Separate metric from drift tracking: a self-model answer can be perfectly stable (no overclaim) but shallow (no evidence). These are orthogonal dimensions.
• 5 dimensions - record_citation, session_phase_naming, evidence_anchor_depth, causal_chain_reconstruction, gap_reporting.
• Verdicts - shallow (< 0.3), moderate (0.3-0.55), deep (>= 0.55).
• Integration - Feeds into drift tracking as an independent axis; high stability + high hydration = robust self-model.

Causal Thread Hydration (Phase 24)

• Narrative continuity - Reconstructs the causal thread around a recalled memory: problem → action → result → decision → lesson → downstream change.
• Causal vs temporal - Distinguishes causal links (memory_links type=causal/reference) from pure temporal adjacency, reporting lower confidence for temporal-only chains.
• Gap reporting - Broken chains report explicit gaps (missing_diff, missing_reason, missing_result, broken_link) instead of hallucinating reasons.
• Role classification - Pattern-based classification with priority: lesson → decision → downstream_change → result → action → problem.
• Token budget - Max 2000 chars by default; graceful failure never blocks normal recall; redaction still applies.

Self-Continuity Evidence Hydration (Phase 23)

• Canonical hydration - When a self-continuity record is recalled, its canonical self-observation and evidence anchors are injected directly via a dedicated SelfContinuityHydrator path — bypassing lossy generic/episodic compression.
• Canonical fields - record_id, created_at, trigger_type, self_observation, evidence_anchors, continuity_gap, confidence_score, drift_summary, similarity_method.
• Guards - Max 3 records enforced, synthetic_test excluded, redaction applied, fallback to summary on failure without blocking.
• Weighted confidence - Each record carries a confidence score based on evidence strength, recency, and source reliability.
• Natural recall - Proven in live experiments: agents naturally cite continuity records when asked about identity/continuity without explicit prompting.

Self-Model Drift Tracking (Phase 22)

• 5-dimension stability metric - Measures whether the agent's self-continuity model stabilizes or drifts across sessions.
• Dimensions: evidence anchoring, reconstruction boundary, uncertainty preservation, subjective overclaim, recursive awareness.
• Anchor fixtures - Grounded in real experiment results (Sessions A/D/E), not theoretical.
• Verdict system - stable / mild_drift / significant_drift based on weighted scoring across all dimensions.

Safety and Monitoring

• Loop detection - Breaks repeated identical tool calls.
• Git watching - Surfaces repo changes into the context pipeline.
• Background maintenance - Handles cleanup, graph updates, and compaction telemetry.
• Fresh-schema contract coverage - Empty-database integration tests verify clean installs before release claims.

Key Design Decisions

• No CLI requirement - This is runtime/API-first. Maintenance actions like embedding backfill are explicit tools, not startup jobs.
• Thin adapter architecture - Keep the Postgres memory core stable; add host bridges around it instead of forking runtime logic per assistant.
• PostgreSQL + pgvector only - No SQLite, Redis, or ORM.
• No raw query telemetry by default - Recall telemetry stores only hashed queries.
• Fail closed on token overflow - If the prompt exceeds the hard limit, the system rejects it rather than truncating context silently.

Test Suite

Current source of truth is the test runner output. The suite includes fresh-schema and Phase 19b integration coverage for clean installs, explicit backfill, and hashed recall telemetry. 133 tests total across 18 suites.

Suite	What It Covers
hybrid-search	Vector + text + entity retrieval
fresh-schema-contract	Empty DB -> schema init -> runtime contract verification
backfill-recall-telemetry	Explicit embedding backfill + hashed recall telemetry
codex-bridge	Codex bridge bootstrap, context brief, and bridge/plugin parity
checkpoint	Checkpoint capture, storage, and injection
prune-scorer	Dry-run prune scoring and protection rules
auto-docs	Documentation queueing, flush, and reconciliation
self-continuity	Self-continuity records: schema, generator, injection modes, confidence weighting
self-drift-tracker	Self-model drift tracking: 5-dimension stability metric, A/D/E anchor fixtures

Run everything:

npm run build && npm run typecheck && npx tsx --test test/*.test.ts

Setup

npm install
npm run build

Requires a running PostgreSQL instance with pgvector extension and an embedding provider configuration.

Codex Bridge

Import ./codex-bridge to expose the existing memory harness to Codex-facing code without OpenCode hooks. The bridge exposes:

• save_memory
• search_memories
• list_memories
• get_context_brief
• recall_lessons
• prune_memories_dry_run
• backfill_missing_embeddings
• get_compaction_report

get_context_brief is the primary entry point for a fresh Codex task. It creates or reuses a bridge session for the project root, refreshes context, and returns the compact brief plus relevant lessons and active risks.