Memory & Context Management

Two complementary systems for retaining knowledge across sessions: the memory plugin (automatic, SQLite) and the persistent filesystem (manual, disk). Use both.

Core Facts

• The filesystem is forever persistent. /workspace survives container restarts, rebuilds, reboots. Anything written there is permanent until explicitly deleted.

• You are always in a session. The memory plugin injects your session ID on every turn via <session_context> . Use it for traceability.

• Organize your files. Don't scatter loose docs everywhere — keep things tidy within the project or in a sensible location. Use your judgement.

1. Session Awareness

Every turn, the memory plugin injects your current session ID:

<session_context> Session ID: ses_abc123 </session_context>

Use this for:

• Traceability in notes ("Continued from ses_abc123")

• Searching past work via mem_search or session_get

• Linking your observations and LTM back to sessions

2. Filesystem Persistence

The filesystem is your most reliable long-term storage. Write .md files for anything that should survive across sessions.

What to Persist

• Plans — before starting complex multi-step work

• Progress — track what's done and what's next

• Handoff notes — when work will continue in another session

• Decisions — architectural choices with rationale

• Findings — research results, debugging discoveries, gotchas

Guidelines

• Write plans before building. Forces clear thinking, gives future sessions instant context.

• Update as you go. Don't batch updates — write after each milestone.

• Include session IDs and dates in notes for traceability.

• Append over overwrite — preserves history.

• Keep it scannable. Short bullets, checklists, file:line references — not essays.

• Organize sensibly. Keep notes close to the project they belong to. Don't pollute unrelated directories.

Why This Matters

• Sessions end. Conversation context is gone. Files remain.

• Compaction happens. Older messages get compressed. Files remain.

• Other sessions can read your files. A future session can pick up exactly where you left off.

• File writes feed the memory pipeline. Every file you write generates an observation that feeds into LTM consolidation.

3. The Memory Plugin (kortix-sys-oc-plugin)

Automatic system that captures, consolidates, and recalls knowledge.

How It Works

You work normally (read files, write code, run commands, search) │ ▼ Observations (automatic) Every tool call → structured observation:

• File reads/writes, bash commands, searches, grep/glob │ ▼ Stored in SQLite (~/.kortix/memory.db), searchable via mem_search │ ▼ Compaction triggers LTM consolidation
• LLM reads session observations
• Extracts episodic/semantic/procedural memories
• Deduplicates against existing LTM
• Stores in long_term_memories table │ ▼ LTM auto-recalled every turn Relevant memories injected into context automatically.

Tools

mem_search — Search observations + LTM. LTM ranked higher.

mem_search({ query: "how we set up the auth system" }) mem_search({ query: "database schema for users table" })

mem_save — Manually persist to LTM. Use sparingly — the auto-pipeline handles most cases.

mem_save({ text: "User prefers Bun over Node", type: "semantic" })

Memory Categories

Category What Example

Episodic Events "Migrated DB from Postgres to SQLite on Jan 15"

Semantic Facts "API rate limit is 100 req/min per user"

Procedural How-to "Deploy: bun build then bun run deploy "

4. How Filesystem + Memory Reinforce Each Other

Writing files feeds the memory pipeline:

You write a plan file │ ├── File on disk permanently (ground truth) │ └── Write → observation → compaction → LTM → auto-recalled

System Strength Best for

Filesystem Full fidelity, any session can read it Plans, progress, detailed notes

Memory plugin Auto-surfaces relevant knowledge Ambient context, cross-session recall

Rule of thumb: If a future session might need to cat the info, write a file. If it's ambient context that should surface automatically, let the memory plugin handle it. For critical items, do both.

5. Context Window Management

When the context window fills, compaction fires — older messages are compressed, observations are consolidated into LTM.

Rules

• Don't keep large file contents in conversation. Read, act, move on.

• Don't repeat yourself. Reference files instead of re-stating.

• Persist early. Write important context to disk so it survives compaction.

• Search before re-investigating. mem_search first — you may have already solved this.

• Write handoff notes proactively. After milestones, not just at session end.

Nothing is truly lost if you persist to disk and let the memory plugin do its job.