Level-of-detail memory tool for coding agent sessions.

Processes a session export file and produces a structured directory of markdown files — one index and one file per logical group — with tiered summaries at increasing levels of detail. Designed so a coding agent can re-enter a long session with minimal context usage while retaining the ability to drill down to full detail on demand.

OpenCode plugin

plugin/lodmem-context.ts is an OpenCode server plugin. It runs a background LOD memory builder on every turn and injects the session index into each LLM call, giving the agent persistent structured memory without storing full file contents in context.

Prerequisites

The plugin imports lodmem source files directly (Bun runs .ts natively). No node_modules are required in .opencode/ — lodmem-context.ts uses only built-in types.

OpenCode patch requirements

Important: If your configuration may trigger OpenCode compaction (session fork), you need to apply patches to OpenCode to ensure lodmem can reuse the parent session's checkpoint data after compaction.

See EVALUATION.md § Running with a custom OpenCode build for detailed patch instructions, requirements, and impact analysis

Setup

1. Symlink the plugin into your project's plugins directory:

   mkdir -p /your/project/.opencode/plugins
   ln -s /path/to/lodmem/plugin/lodmem-context.ts \
         /your/project/.opencode/plugins/lodmem-context.ts

2. Create .lodmemrc in your project root. Choose one of two provider modes:

   Option A — OpenCode-managed model (no separate API key needed; uses any model already configured in OpenCode):

   {
     "provider": "opencode",
     "ocProviderID": "github-copilot",
     "ocModelID": "gpt-4o"
   }

   Supported ocProviderID values match what opencode models lists (e.g. "anthropic", "openai", "github-copilot").

   Option B — OpenAI-compatible endpoint (bring your own key/endpoint):

   {
     "provider": "openai",
     "baseUrl": "http://127.0.0.1:14300/v1",
     "apiKey": "",
     "model": "gpt-4o-mini"
   }

   Both options accept optional tuning fields:

   {
     "groupTokenThreshold": 128000,
     "maxGroupDepth": 4,
     "temperature": 0.2,
     "maxResponseTokens": 2048,
     "outputDir": "",
     "trimContextThreshold": 60000
   }

   outputDir defaults to ~/.lodmem/opencode/<project-hash>/ (recommended — keeps lodmem files out of the project tree). Set to a relative or absolute path to override.

The plugin reads config from ~/.lodmemrc and ./.lodmemrc on every turn (project-local wins). If no .lodmemrc is present the plugin falls back to the openai provider defaults, which will fail validation — ensure at minimum a provider is configured.

3. Sample Configuration:

OpenCode with GitHub Copilot:

{
  "provider": "opencode",
  "ocProviderID": "github-copilot",
  "ocModelID": "claude-haiku-4.5",
  "groupTokenThreshold": 128000,
  "maxGroupDepth": 4,
  "temperature": 0.2,
  "maxResponseTokens": 2048,
  "trimContextThreshold": 80000
}

Opencode with Anthropic via OpenCode:

{
  "provider": "opencode",
  "ocProviderID": "anthropic",
  "ocModelID": "claude-haiku-4-5",
  "groupTokenThreshold": 128000,
  "maxGroupDepth": 4,
  "temperature": 0.2,
  "maxResponseTokens": 2048,
  "trimContextThreshold": 80000
}

How the plugin works at runtime

• system.transform — injects a stable one-time directive telling the agent where to find the session index. Text never changes, so the system prompt cache hit rate is unaffected.
• messages.transform — runs an incremental background LOD build (categorise new turns → update checkpoint → render index.md to disk). Injects a short path notice into the last user message so the agent knows where to read. Trims old messages once context exceeds trimContextThreshold.
• session.compacting — when OpenCode compacts the session, replaces the default summary with a structured lodmem prompt that preserves the group index, current task list, and recent turn detail.

Sidecar LLM sessions (provider=opencode)

When provider=opencode, lodmem creates a dedicated sidecar OpenCode session to run its categorisation calls. The sidecar session is:

• Created lazily on the first background build and reused for the lifetime of the agent session.
• Created with parentID set to the main agent session ID. This causes OpenCode's GitHub Copilot integration to classify all sidecar requests as x-initiator: agent rather than x-initiator: user, so they do not count as premium requests.
• Protected against forkbomb: every plugin hook checks sidecarSessionIDs and returns immediately for sidecar sessions, preventing the sidecar's own turns from triggering a new build cycle.

How it works

1. Categorise — each turn is assigned to one or more logical groups (GOAL, FILE, CODE, OUTPUT, EDIT, OTHER).
2. Summarise — each group gets tiered LOD summaries: LOD-1 is a single sentence, LOD-2 is structured detail, and LOD-max is a machine-readable retrieval instruction so the agent can fetch full content on demand without storing it verbatim.

Groups that exceed the configured token threshold are recursively subdivided by the LLM until each fits within budget.

The ~/.loadmem/ directory contains:

• index.md — LOD-1 summaries for all groups (inject this into a new session)
• groups/<group-id>.md — full multi-level detail per group
• sidecars/ — raw content for large tool outputs (command logs, file reads)
• .checkpoint.json — incremental state so re-runs only process new turns

Prerequisites

OpenCode Plugin

• An LLM endpoint — either:
  • An OpenAI-compatible HTTP API (OpenAI, Anthropic via proxy, local Ollama/LM Studio, etc.), or
  • OpenCode already running with at least one provider configured (opencode models lists available models)

Development

• Node.js 20+ and pnpm (for building the CLI)
• Bun (for running the OpenCode plugin — OpenCode uses Bun natively)

Installation

After building, the lodmem binary is at dist/cli.js. You can run it with:

node dist/cli.js <command>
# or
pnpm start <command>
# or during development (no build required):
pnpm dev <command>

To install globally from the repo root:

npm install -g .
lodmem --version

Configuration

Config is loaded in priority order — later sources win:

1. ~/.lodmemrc (user-global JSON)
2. ./.lodmemrc (project-local JSON, gitignored)
3. Environment variables
4. CLI flags

.lodmemrc format

Copy .lodmemrc.example to .lodmemrc and edit. Two provider modes are supported:

provider=openai — any OpenAI-compatible endpoint:

{
  "provider": "openai",
  "baseUrl": "https://api.openai.com/v1",
  "apiKey": "${OPENAI_API_KEY}",
  "model": "gpt-4o-mini",
  "groupTokenThreshold": 2000,
  "maxGroupDepth": 4,
  "temperature": 0.2,
  "maxResponseTokens": 2048
}

provider=opencode — delegate to an OpenCode-managed model; no separate credentials needed:

{
  "provider": "opencode",
  "ocProviderID": "github-copilot",
  "ocModelID": "gpt-4o"
}

ocProviderID and ocModelID must match a model listed by opencode models. This provider is only available when lodmem is running as an OpenCode plugin (not from the CLI).

The ${VAR_NAME} syntax in config values is expanded from environment variables.

Environment variables

Commands

process

Process a session file and write a LOD memory directory.

lodmem process <session-file> -o <output-dir> [options]

Arguments:
  session-file            Path to the session export file (OpenCode .md export)

Required:
  -o, --output <path>     Output directory for the LOD memory files

Options:
  --full                  Ignore checkpoint; reprocess the entire session
  --config <path>         Path to a specific .lodmemrc config file
  --api-key <key>         LLM API key (overrides config/env)
  --model <model>         LLM model name (overrides config/env)
  --base-url <url>        LLM API base URL (overrides config/env)
  --threshold <n>         Token threshold for group subdivision (overrides config/env)
  --max-turns <n>         Stop after processing this many turns (useful for testing)
  -q, --quiet             Suppress progress output

Example:

lodmem process sessions/my-session.md -o .lodmem/my-session

On success, the output directory path is written to stdout. Re-running with the same output directory uses the checkpoint to skip already-processed turns. Use --full to force a complete reprocess.

query

Ask a natural-language question against a LOD memory directory.

lodmem query <lod-dir> <question> [options]

Arguments:
  lod-dir                 Path to the LOD memory directory (output of 'process')
  question                Natural-language question

Options:
  --full                  Load all group files for full detail (more tokens used)
  --config <path>         Path to a specific .lodmemrc config file
  --api-key <key>         LLM API key (overrides config/env)
  --model <model>         LLM model name (overrides config/env)
  --base-url <url>        LLM API base URL (overrides config/env)

Example:

lodmem query .lodmem/my-session "What tests were failing and why?"

By default only LOD-1 summaries (the index) are sent to the LLM. Use --full to include all group detail files.

inspect

Print all LOD levels for a specific group.

lodmem inspect <lod-dir> <group-id> [options]

Arguments:
  lod-dir                 Path to the LOD memory directory
  group-id                Group ID or unique prefix (e.g. "goal:add-unit" or just "goal")

Options:
  --level <n>             Show only this detail level (e.g. --level 2)
  --sidecar               Also print the sidecar file for this group if one exists

Example:

lodmem inspect .lodmem/my-session goal:add-unit-tests
lodmem inspect .lodmem/my-session goal:add-unit-tests --level 2
lodmem inspect .lodmem/my-session output:test-run --sidecar

Partial prefix matching is supported — if only one group ID starts with the given prefix, it is used automatically.

Output directory structure

<output-dir>/
  index.md                  # LOD-1 summaries for all groups (inject into new session)
  groups/
    goal--add-unit-tests.md # Per-group file with all detail levels
    file--src-cli-ts.md
    output--test-run.md
    ...
  sidecars/
    output--test-run.txt    # Raw content for large command outputs / file reads
  .checkpoint.json          # Incremental state for re-runs

index.md format

The index lists all groups with their LOD-1 summary and a machine-readable group comment:

# lodmem: <session title>
**Generated:** ...  **Turns:** N  **Groups:** M

---

<!-- LODMEM:group id="goal:add-unit-tests" type="GOAL" -->
## GOAL — Add unit tests

**LOD-1:** Add comprehensive vitest unit tests for all source modules.

<!-- LODMEM:retrieve group="goal:add-unit-tests" -->

Per-group file format

Each group file contains multi-level detail:

<!-- LODMEM:group id="goal:add-unit-tests" type="GOAL" -->
# Add unit tests

<!-- LODMEM:level n="1" label="summary" -->
Add comprehensive vitest unit tests for all source modules.

<!-- LODMEM:level n="2" label="detail" -->
Tests were added for: opencode-md-parser (18), config-loader (14),
checkpoint (11), lod-renderer (19), lod-builder (7).

<!-- LODMEM:read type="turns" range="0-12" -->

Incremental processing

A .checkpoint.json is written alongside the output files:

{
  "sessionFile": "/path/to/session.md",
  "sessionHash": "<sha256>",
  "lastTurnIndex": 47,
  "groupHashes": {
    "goal:add-unit-tests": "<sha256>",
    "file:src/cli.ts": "<sha256>"
  }
}

On re-run, only turns after lastTurnIndex are sent to the LLM for categorisation. Groups whose content hash is unchanged are not re-summarised.

Use --full to ignore the checkpoint and reprocess everything from scratch.

Development

pnpm install          # Install dependencies
pnpm build            # Compile TypeScript to dist/
pnpm typecheck        # Type-check without emitting
pnpm dev <args>       # Run CLI directly via tsx (no build required)
pnpm test             # Run all tests (vitest)
pnpm test:watch       # Watch mode

Running against the sample session

A sample session export is included at samples/session-add_unit_tests.md. To run lodmem process against it:

pnpm build
node dist/cli.js process samples/session-add_unit_tests.md -o /tmp/lodmem-sample --full

To limit LLM usage during testing, use --max-turns:

node dist/cli.js process samples/session-add_unit_tests.md -o /tmp/lodmem-sample --full --max-turns 5

After processing, inspect the output:

# View the index (LOD-1 summaries)
cat /tmp/lodmem-sample/index.md

# List all groups
ls /tmp/lodmem-sample/groups/

# Inspect a specific group
node dist/cli.js inspect /tmp/lodmem-sample goal

# Query the memory
node dist/cli.js query /tmp/lodmem-sample "What was the main goal of this session?"

Test structure

Tests live alongside source files:

All tests use vitest with a mock LLM provider — no real LLM calls are made during tests.

Evaluation harness

eval/run_eval.sh runs a single lodmem eval condition against a task and collects metrics.

Usage

# No lodmem (control)
./eval/run_eval.sh --task pygrep --condition baseline

# lodmem with an OpenAI-compatible endpoint
./eval/run_eval.sh --task pygrep --condition lodmem \
  --model gpt-4o-mini \
  --base-url http://127.0.0.1:14300/v1 \
  --api-key ""

# lodmem using an OpenCode-managed model (no separate credentials needed)
./eval/run_eval.sh --task pygrep --condition opencode-lodmem \
  --oc-provider-id github-copilot \
  --oc-model-id gpt-4o

Each run is isolated in /tmp/lodmem-eval/<task>/<timestamp>_<condition>/. Logs and a metrics.json are copied back to eval/<task>/runs/<timestamp>_<condition>/ when done.

Key flags

metrics.json

Each run produces eval/<task>/runs/<timestamp>_<condition>/metrics.json:

{
  "task": "pygrep",
  "condition": "opencode-lodmem",
  "exit_code": 0,
  "wall_seconds": 100,
  "tokens": {
    "input": 31,
    "output": 13251,
    "cache_read": 202013,
    "cache_write": 171302
  },
  "cost_usd": 0.30,
  "sidecar": {
    "calls": 30,
    "input_tokens": 0,
    "output_tokens": 0
  }
}

sidecar.calls counts the number of categorisation LLM calls made by the lodmem background builder (one per new turn processed). For provider=opencode, input_tokens and output_tokens are always 0 because the OpenCode session API does not return token counts; use sidecar.calls as the primary overhead metric instead.

Note: sidecar costs are not included in cost_usd. The cost_usd field reflects only the main agent session (as reported by OpenCode's step_finish events). For provider=opencode with github-copilot/gpt-4o, sidecar calls are classified as agent requests and are free.

Analysing results

python3 eval/evaluate.py --task pygrep --latest

Supported session formats

Currently supported:

• OpenCode markdown export — the .md format produced by OpenCode's session export feature. Detected automatically by the presence of an OpenCode session header.

The parser interface is pluggable (src/parser/parser-interface.ts), making it straightforward to add support for additional formats.