Context & Memory

The Problem: LLMs Don't Remember

Large Language Models have a fixed context window (typically 8k–200k tokens). Once the conversation scrolls past that limit, older information is lost. Without memory, every session starts from scratch — the agent doesn't know what decisions were made, what conventions were established, or what code patterns were agreed upon in the last session.

Krnl solves this with a three-layer memory system: project memory (persistent conventions), session memory (structured facts per session), and context compaction (fitting more into the window).

With vs. Without Context & Memory

The same task in a second session — “add a DELETE endpoint for users” — with and without per-session memory:

Without Memory — Every session starts fresh

With Memory — The agent remembers past decisions

Memory Layers

Krnl uses three distinct memory layers, each with a different scope and lifetime:

Conversation Compaction

Long conversations consume tokens. Krnl automatically compacts history when it approaches the configured max_context_tokens limit:

• Tool output trimming — Old tool results are replaced with a note (“previous output truncated”), keeping only the last N results at full length.
• Assistant message truncation — Older assistant responses are shortened to 500 characters.
• LLM summarization — When enabled, the middle of the conversation is replaced with a short LLM-written summary instead of naive truncation.
• Differential tracking — Files and graph nodes already sent to the model are never resent — only diffs are transmitted.

Project Memory (AGENTS.md)

Project memory is the most visible memory layer. It's a markdown file (AGENTS.md, KRNL.md, or CLAUDE.md) that lives in your project root or under .krnl/. It's loaded into every session's system prompt automatically.

# Project memory for MyApp

## Commands
- Build: npm run build
- Test: npm test
- Lint: npm run lint

## Conventions
- Use camelCase for API endpoints
- Use db.query() for all database access
- Prefer async/await over callbacks
- Error responses: { error: string, code: number }

## Notes
- The auth middleware is in src/middleware/auth.ts
- We use JWT tokens with 1h expiry

Krnl also checks for a user-global memory file at ~/.krnl-code/AGENTS.md which applies to all projects (for personal preferences like “always use tabs” or “prefer TypeScript over JavaScript”).

Per-Session Memory

When enabled, Krnl stores structured memory entries per session: facts, decisions, errors, and solutions. Each entry is tagged with the files it relates to.

When you start a new session and mention a file, Krnl loads only the memory entries relevant to that file — it doesn't dump everything. If the code graph is enabled, entries are automatically marked stale when their referenced files are deleted or renamed (no stale advice).

Memory V2 — Structured Memory Fabric

Memory V2 is a durable, multi-store memory system that turns long agent runs into structured state. Unlike per-session memory (which stores simple key-value entries), Memory V2 maintains seven specialized stores that capture the full picture of what the agent knows and does.

The Seven Stores

How It Works

Memory V2 uses an append-only event log backed by SQLite. Every agent action — messages, tool calls, file edits, plan updates — emits a typed event. Seven reducers project these events into the structured stores in real time.

Automatic Reference Extraction

Memory V2 automatically extracts file paths and symbol references from assistant messages and tool execution output. This means the working context stays up to date without the agent explicitly declaring what it's working on.

• Assistant messages — file paths and function names mentioned in responses are added to working context
• Tool arguments — the path parameter from write_file, edit_file, read_file is automatically tracked
• Tool output — references found in command output and tool results are extracted and merged

Smart Requirement Change Detection

When the user sends a follow-up message, Memory V2 compares it against the previous message using a 40% word-overlap threshold. Messages that share more than 40% vocabulary are considered continuations (e.g., “also add tests”), while low-overlap messages trigger a requirement change checkpoint (e.g., “switch from OAuth to SAML”).

Error and Solution Tracking

The memory_write tool now supports four memory types, with errors and solutions projected into categorized facts for intelligent retrieval:

# Store a fact
memory_write(type="fact", content="The API uses camelCase", related_files=["src/api.ts"])

# Record a decision
memory_write(type="decision", content="Use JWT for auth, not sessions", related_files=["src/auth.ts"])

# Log an error (NEW in v2.2.4+)
memory_write(type="error", content="TypeError: Cannot read property 'id' of undefined", related_files=["src/handler.ts"])

# Record a solution (NEW in v2.2.4+)
memory_write(type="solution", content="Added null check before accessing .id property", related_files=["src/handler.ts"])

Errors and solutions are automatically stored as categorized facts with keys like error:TypeError... and solution:null check..., making them searchable and retrievable when similar issues arise.

Lifecycle and Retention

Memory V2 includes automatic lifecycle management to prevent unbounded growth:

• Event trimming — keeps only the most recent N events per session (configurable)
• Working context expiry — stale context records are removed after a configurable TTL
• Task archival — completed tasks are rolled up into the completed_work store
• Atomic cleanup — all lifecycle operations run in a single SQLite transaction with rollback on error

Full-Text Search

All events are indexed by SQLite FTS5 for keyword-based retrieval. The agent can search across the entire event history to find relevant context:

# Search across all events
results = memory_manager.search_events("rate limiting")
# Returns events mentioning "rate limiting" ranked by relevance

# FTS5 special characters are safely escaped
results = memory_manager.search_events('config with "quotes" and (parens)')

Differential Context Tracking

Once a file or graph node has been sent to the model, it doesn't need to be resent on the next step. Krnl tracks exactly what was sent using content hashes for files and node IDs for graph nodes. On subsequent turns, only new or changed content is transmitted.