nl-session-memory-context-compaction

An educational local C# project showing how long-running AI agent sessions can stay bounded by combining pinned facts, rolling summaries, expiry rules, conflict resolution, deterministic context budgeting, and an optional local Ollama response path.

This version uses a coding agent scenario with a multi-turn checkout bug-fix session, carry-forward state snapshots, an optional Ollama-generated next-turn draft, and file-backed JSON reports.

Overview

This repository demonstrates a practical session-memory control flow:

1. Load runtime configuration for dataset path, report directory, token budget, recent-turn window, summary depth, and fact TTLs.
2. Replay a frozen multi-turn coding-agent session from JSON.
3. Normalize fact writes before storage, including trimming, max-length checks, and secret redaction.
4. Keep pinned constraints and goals durable across turns.
5. Expire short-lived or stale session facts before the next carry-forward snapshot.
6. Resolve conflicting fact writes deterministically so newer trusted facts replace weaker ones.
7. Compact older interaction history into a rolling summary while preserving the most recent turns.
8. Pack the next-turn context under an explicit token budget and exclude blocks that should not survive.
9. Optionally send only the packed carry-forward context to a local Ollama model for the next-turn draft.
10. Persist the full turn-by-turn report as JSON for later inspection.

The result is a real context-engineering control layer without pretending that raw chat history should be passed forward indefinitely.

What This Project Demonstrates

• Deterministic session memory for long-running AI agent conversations
• Pinned facts for goals, constraints, and verification commands
• Rolling summaries that compress older turns once the recent-turn window is exceeded
• TTL-based expiry for short-lived session notes
• Conflict resolution where newer trusted facts override earlier values
• Secret redaction before memory persistence
• Explicit carry-forward budgeting with included and excluded context blocks
• Optional Ollama-backed next-turn drafting over deterministic carry-forward state
• File-backed JSON reports showing every turn snapshot and final prompt preview

Prerequisites

• .NET 10 SDK or later
• Optional for live model drafting:
  • Ollama running locally at http://localhost:11434
  • a pulled chat-capable model such as qwen3:8b

The deterministic compaction pipeline always runs locally against the frozen session dataset. The model stage is optional and uses only the packed carry-forward context.

Quick Start

From the project root:

ollama serve
dotnet test SessionMemoryContextCompaction.slnx
dotnet run --project SessionMemoryContextCompaction

The app prints:

• active, expired, superseded, and rejected fact counts per turn
• token usage for every carry-forward snapshot
• the final active verification command after conflict resolution
• an optional Ollama-generated next-turn draft or a model error if Ollama is unavailable
• the saved JSON report path

Configuration

Default settings are in SessionMemoryContextCompaction/appsettings.json under App.

Example:

{
  "App": {
    "DatasetPath": "data/coding_agent_session.json",
    "ReportDirectory": "data/reports",
    "ModelContextWindowTokens": 2200,
    "ReservedOutputTokens": 450,
    "FixedPromptTokens": 240,
    "MaxRecentTurns": 2,
    "MaxSummaryEntries": 4,
    "DefaultFactTtlMinutes": 180,
    "ShortLivedFactTtlMinutes": 30,
    "MaxFactValueChars": 280,
    "EnableModelCall": true,
    "OllamaBaseUrl": "http://localhost:11434",
    "OllamaModelId": "qwen3:8b",
    "OllamaTimeoutSeconds": 45,
    "OllamaTemperature": 0.0,
    "OllamaMaxOutputTokens": 220
  }
}

Environment variable overrides use prefix CTXMEM_:

• CTXMEM_App__DatasetPath
• CTXMEM_App__ReportDirectory
• CTXMEM_App__ModelContextWindowTokens
• CTXMEM_App__ReservedOutputTokens
• CTXMEM_App__FixedPromptTokens
• CTXMEM_App__MaxRecentTurns
• CTXMEM_App__MaxSummaryEntries
• CTXMEM_App__DefaultFactTtlMinutes
• CTXMEM_App__ShortLivedFactTtlMinutes
• CTXMEM_App__MaxFactValueChars
• CTXMEM_App__EnableModelCall
• CTXMEM_App__OllamaBaseUrl
• CTXMEM_App__OllamaModelId
• CTXMEM_App__OllamaTimeoutSeconds
• CTXMEM_App__OllamaTemperature
• CTXMEM_App__OllamaMaxOutputTokens

Disable live model drafting:

set CTXMEM_App__EnableModelCall=false
dotnet run --project SessionMemoryContextCompaction

How It Works

1. Program.cs loads config, replays the frozen session, optionally invokes Ollama with the packed final context, saves the report, and prints the final carry-forward summary.
2. SessionDatasetLoader loads the multi-turn session dataset from JSON.
3. MemoryWritePolicy validates fact writes, assigns TTLs, and redacts secrets before anything is stored.
4. ContextCompactionEngine expires stale facts, applies deterministic conflict resolution, builds rolling summaries, and packs the next-turn context under budget.
5. NextTurnPromptComposer turns the final carry-forward snapshot into a bounded model prompt.
6. OllamaDraftClient calls the local Ollama /api/generate endpoint and strips <think> traces from the returned draft.
7. JsonReportStore persists the turn-by-turn compaction report for later replay and inspection.

Project Structure

.
+-- SessionMemoryContextCompaction.slnx
+-- SessionMemoryContextCompaction/
|   +-- SessionMemoryContextCompaction.csproj
|   +-- Program.cs
|   +-- appsettings.json
|   +-- App/
|   |   +-- AppConfig.cs
|   +-- Domain/
|   |   +-- CompactionReport.cs
|   |   +-- MemoryFact.cs
|   |   +-- SessionDataset.cs
|   +-- Persistence/
|   |   +-- JsonReportStore.cs
|   +-- Services/
|       +-- ContextCompactionEngine.cs
|       +-- HeuristicTokenEstimator.cs
|       +-- MemoryWritePolicy.cs
|       +-- NextTurnPromptComposer.cs
|       +-- OllamaDraftClient.cs
|       +-- SecretRedactor.cs
|       +-- SessionDatasetLoader.cs
|   +-- data/
|       +-- coding_agent_session.json
+-- SessionMemoryContextCompaction.Tests/
|   +-- SessionMemoryContextCompaction.Tests.csproj
|   +-- ContextCompactionEngineTests.cs
|   +-- SecretRedactorTests.cs
+-- .gitignore
+-- LICENSE
+-- README.md

Control Guarantees

• Pinned task constraints survive across turns unless a newer trusted source intentionally changes them
• Short-lived notes expire before they silently distort later model calls
• Older history is compacted into a bounded rolling summary instead of being replayed in full
• Redacted secrets are not carried into the next-turn context
• The carry-forward state is built under an explicit token budget, with exclusions recorded by reason
• The live model sees only the packed carry-forward context, never the raw full transcript

Tests

Run the test project from the repo root:

dotnet test SessionMemoryContextCompaction.slnx

The current test suite covers:

• pinned fact survival across turns
• expiry of short-lived facts
• deterministic override of an updated verification command
• rolling-summary creation once the recent-turn window is exceeded
• redacted secret exclusion from carry-forward context
• next-turn prompt composition
• cleanup of <think> traces from model output

License

See the LICENSE file for details.

Contributing

Contributions are welcome for improvements within current project scope.

Suggested areas:

• add more session scenarios such as support operations or incident coordination
• introduce per-scope TTL policies and stronger conflict rules
• calibrate token estimation against real model tokenizers
• extend the report format with longitudinal snapshot comparisons