HN 표시: Lodmem – 에이전트에 대한 세부 수준 컨텍스트 관리

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. 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. 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. - 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 - 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 whatopencode 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// (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. - Sample Configuration: { "provider": "opencode", "ocProviderID": "github-copilot", "ocModelID": "claude-haiku-4.5", "groupTokenThreshold": 128000, "maxGroupDepth": 4, "temperature": 0.2, "maxResponseTokens": 2048, "trimContextThreshold": 80000 } { "provider": "opencode", "ocProviderID": "anthropic", "ocModelID": "claude-haiku-4-5", "groupTokenThreshold": 128000, "maxGroupDepth": 4, "temperature": 0.2, "maxResponseTokens": 2048, "trimContextThreshold": 80000 } 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 → renderindex.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 exceedstrimContextThreshold .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. 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 asx-initiator: agent rather thanx-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. - Categorise — each turn is assigned to one or more logical groups (GOAL, FILE, CODE, OUTPUT, EDIT, OTHER). - 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/.md — full multi-level detail per groupsidecars/ — raw content for large tool outputs (command logs, file reads).checkpoint.json — incremental state so re-runs only process new turns - 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) - Node.js 20+ and pnpm (for building the CLI) - Bun (for running the OpenCode plugin — OpenCode uses Bun natively) pnpm install pnpm build After building, the lodmem binary is at dist/cli.js . You can run it with: node dist/cli.js # or pnpm start # or during development (no build required): pnpm dev To install globally from the repo root: npm install -g . lodmem --version Config is loaded in priority order — later sources win: ~/.lodmemrc (user-global JSON)./.lodmemrc (project-local JSON, gitignored)- Environment variables - CLI flags 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. | Variable | Description | |---|---| LODMEM_API_KEY | LLM API key | LODMEM_MODEL | Model name | LODMEM_BASE_URL | API base URL | LODMEM_THRESHOLD | Token threshold per group | LODMEM_TRIM_THRESHOLD | Context token threshold at which old messages are trimmed | LODMEM_MODE | continuous (default) or compact-only | LODMEM_DEBUG | Set to 1 to enable verbose debug logging to /lodmem.log | Process a session file and write a LOD memory directory. lodmem process -o [options] Arguments: session-file Path to the session export file (OpenCode .md export) Required: -o, --output Output directory for the LOD memory files Options: --full Ignore checkpoint; reprocess the entire session --config Path to a specific .lodmemrc config file --api-key LLM API key (overrides config/env) --model LLM model name (overrides config/env) --base-url LLM API base URL (overrides config/env) --threshold Token threshold for group subdivision (overrides config/env) --max-turns 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. Ask a natural-language question against a LOD memory directory. lodmem query [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 to a specific .lodmemrc config file --api-key LLM API key (overrides config/env) --model LLM model name (overrides config/env) --base-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. Print all LOD levels for a specific group. lodmem inspect [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 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. / 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 The index lists all groups with their LOD-1 summary and a machine-readable group comment: # lodmem: **Generated:** ... **Turns:** N **Groups:** M --- ## GOAL — Add unit tests **LOD-1:** Add comprehensive vitest unit tests for all source modules. Each group file contains multi-level detail: # Add unit tests Add comprehensive vitest unit tests for all source modules. Tests were added for: opencode-md-parser (18), config-loader (14), checkpoint (11), lod-renderer (19), lod-builder (7). A .checkpoint.json is written alongside the output files: { "sessionFile": "/path/to/session.md", "sessionHash": "", "lastTurnIndex": 47, "groupHashes": { "goal:add-unit-tests": "", "file:src/cli.ts": "" } } 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. pnpm install # Install dependencies pnpm build # Compile TypeScript to dist/ pnpm typecheck # Type-check without emitting pnpm dev # Run CLI directly via tsx (no build required) pnpm test # Run all tests (vitest) pnpm test:watch # Watch mode 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?" Tests live alongside source files: | File | Tests | Coverage | |---|---|---| src/parser/opencode-md-parser.test.ts | 18 | Parser detection, metadata, turn roles, all tool types | src/config/config-loader.test.ts | 14 | Config layering, env vars, CLI overrides, validation | src/lod/checkpoint.test.ts | 11 | Checkpoint save/reload, session change detection, group hashing | src/lod/lod-renderer.test.ts | 19 | File creation, index format, group files, LOD levels, sidecars | src/lod/lod-builder.test.ts | 7 | buildLodMemory with mock LLM, progress callbacks, error fallback | All tests use vitest with a mock LLM provider — no real LLM calls are made during tests. eval/run_eval.sh runs a single lodmem eval condition against a task and collects metrics. # 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//_/ . Logs and a metrics.json are copied back to eval//runs/_/ when done. | Flag | Default | Description | |---|---|---| --task | — | Task name under eval/ (e.g. pygrep , pyssh ) | --condition | — | baseline , lodmem , opencode-lodmem | --oc-provider-id | — | OpenCode provider ID (required for opencode-lodmem ) | --oc-model-id | — | OpenCode model ID (required for opencode-lodmem ) | --model | — | Model ID (required for lodmem ) | --base-url | — | API base URL (required for lodmem ) | --timeout | 0 (none) | Wall-clock timeout in seconds; kills opencode after N seconds | --lodmem-mode | continuous | continuous or compact-only | --compaction-reserved | — | OpenCode compaction.reserved value (tokens) | --min-tests | 40 | Minimum test count injected into the task prompt | --pad-tokens | 2000 | Synthetic context padding tokens (0 to disable) | Each run produces eval//runs/_/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. python3 eval/evaluate.py --task pygrep --latest 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.