All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
- Added bundled
researchandcompliancesignal profiles, registered as first-class source profiles alongside coding, support, ops, and generic. - Added realistic multi-turn example traces for support, incident, research, and compliance workflows, replacing the earlier two-line toy traces.
- Added before/after demo guides for support ops, incident ops, research, and compliance, each showing real extracted records captured through extraction.
- Added a custom and non-coding agents front-door guide covering the profile, clean-trace, import, query, and improvement-loop path.
- Added a defense-in-depth redaction helper (
scripts/redact_trace.py) that strips common secrets and PII from a trace before import. - Added an agent improvement loop diagram to the README and custom-agents guide.
- Updated the README with a Custom and Non-Coding Agents section, the bundled profile table, and links to the vertical demos.
- Updated the docs navigation, examples index, and custom-trace submission guide to cover the new profiles, demos, and redaction helper.
- Updated the custom-trace-folder and context-retrieval diagrams to use neutral support and research agent examples instead of removed third-party logos.
- Fixed dashboard operation detail logs so they honor the selected project instead of falling back to shared logs.
- Fixed project-scoped operations activity by paging through the session catalog until matching project runs are found.
- Hardened source-session catalog migrations and FTS rebuilds so older or malformed catalogs recover into a healthy indexed state for graph and source views.
- Fixed dashboard graph project switching by enforcing selected-project scope on graph responses and clearing stale graph data during project reloads.
- Made dashboard record, graph, artifact, operations, and source views fail closed instead of preserving stale rows after scoped load failures.
- Fixed the Records tab "All statuses" filter so it returns active and archived project records instead of falling back to the active-only default.
- Hardened the dashboard launcher against mismatched backend versions so an old local API cannot silently serve stale project data to a newer dashboard.
- Made invalid project selections return clear errors for status, memory, and Clinic endpoints, and kept refine reports degraded instead of crashing when the session catalog is unavailable.
- Updated the offline release integration expectation for project-list count fields so the release workflow validates the new dashboard project counts.
- Made dashboard project selection visibly affect graph, records, brief, Clinic, source, operations, overview, and insights views, while keeping shared runtime surfaces clearly labeled.
- Separated current active, archived, and total persisted record counts across project lists, status payloads, and Run Clinic.
- Fixed plain missing project names being interpreted as relative paths, so invalid dashboard project selections now return a clear error instead of falling back to the current workspace.
- Scoped graph queries, record filters, run detail reads, and artifact history through the selected project, including child workspace paths.
- Kept
lerim serveand dashboard session-backed endpoints available in a degraded state when the source-session catalog is unhealthy.
- Added project selection to the dashboard surfaces that read project-scoped data, including overview, analytics, context, graph, traces, memory artifacts, operations, and Run Clinic.
- Added the Run Clinic dashboard artifact surface and project-scoped generated artifact history views.
- Kept selected projects in dashboard navigation URLs while leaving shared Skills and Settings views unscoped.
- Labeled shared runtime and multi-project operation rows clearly when they appear inside a project-scoped dashboard view.
- Scoped dashboard status, queue, source-session, graph, artifact-history, and record-open reads to the selected project, including child workspace paths.
- Prevented cross-project artifact history and mixed-project operation totals from leaking into project-scoped dashboard views.
- Added README and docs guidance for registering skill targets, reviewing skill update proposals, and using opt-in auto-apply.
- Refined the Skills dashboard proposal review into a desktop queue/detail layout with explicit risk labels and cleaner applied-proposal state.
- Reduced normal dashboard tab gutters so pages use the available workspace with compact responsive padding.
- Added skill stewardship registration, refresh, proposal review, diff preview, and apply/reject flows across the CLI, API, and dashboard.
- Added scoped record loading, artifact-surface validation, and opt-in auto-apply policy controls for registered instruction targets.
- Hardened skill proposal application so stale concurrent apply attempts cannot revert files after a proposal has already been marked applied.
- Removed stale release and docs workflow references to the deleted support-boundary SVG generator.
- Refactored context-answering, context-brief, trace-ingestion, and working-memory agents onto DSPy pipelines.
- Simplified Working Memory handoff output so startup context stays focused on useful continuation context instead of task-list noise.
- Restored the release metadata path after the failed post-
0.3.11tags by publishing the current release candidate under a fresh version.
- Added a persistent node type legend to the dashboard Context Graph canvas so record-kind colors are readable without opening the inspector panel.
- Replaced the dashboard Context Graph renderer with AntV G6, keeping the graph focused on topic clustering and clustering-off modes.
- Improved the clustering-off graph with record-kind node colors, a compact topology layout, and a record type legend.
- Returned durable record kinds in graph API node payloads so dashboard node colors reflect the real data catalog instead of the derived context-node type.
- Added the Working Memory dashboard surface, API/runtime support, CLI and concept documentation, and unit coverage for working-memory behavior.
- Improved the Context Graph topic visualization with real node-bounded cluster clouds, cleaner semantic cluster labels, draggable cluster handles, overlap guarding, and less noisy focused-edge rendering.
- Updated dashboard navigation, context brief surfaces, and supporting docs for the working-memory flow.
- Added an Insights memory timeline with created, revised, archived, and active context signals over the selected time window.
- Added clickable changed-memory drilldown rows with a detail modal for memory body, typed fields, provenance, and version metadata.
- Grouped Insights charts into separate Memory Timeline and Source Activity sections while keeping one shared page-level time window selector.
- Hid empty model and tool diagnostic charts until indexed trace metadata exists, while keeping the readiness note visible.
- Made
lerim dashboarda local dashboard launcher that ensures the backend is reachable, installs dashboard npm dependencies when needed, starts the Next.js UI, and prints the dashboard URL. - Added
lerim dashboard --portfor choosing the local dashboard UI port.
- Added the open-source dashboard to the main Lerim repository.
- Served the context graph dashboard from learned graph data, including real
context_nodesandcontext_edges, instead of the old record-only fallback.
- Added a public custom trace folder flow asset to the custom trace guide.
- Updated the release workflow, Docker runtime pull target, OCI source label,
PyPI metadata, README links, and docs repo links after the GitHub repository
rename from
lerim-clitolerim. - Changed GHCR publishing and
lerim updefaults toghcr.io/lerim-dev/lerimafter the old CLI package name was retired. - Clarified that MCP config support provides context retrieval and explicit
lerim_trace_submit, not automatic completed-session capture, and documented the OpenClaw/custom clean trace boundaries.
- Made
lerim answerreport real internal answerer failures as HTTP 500 while reserving HTTP 504 for the configured five-minute answer deadline. - Aligned CLI, server, and BAML model-call timeout contracts so complicated answer queries can run up to the five-minute budget without being cut off by a shorter layer.
- Added semantic retries for invalid context-answer retrieval plans and placeholder-only final answers, preventing bad model outputs from becoming successful CLI responses.
- Generalized imported market-baseline benchmark artifacts and docs so public benchmark structure is not organized around one competitor-specific name.
- Kept release benchmark pages on the clean public artifact numbers while preserving source/provenance boundaries for imported competitor rows.
- Hardened coding trace ingestion against one-way implementation runs that should be archived without durable records.
- Improved coding extraction retention for user strategy, project identity, and supported coding-context records before persistence.
- Added a Python-first MCP server with context brief, context answer, context search, deterministic records listing, trace submission, and ingest/status tools.
- Added
lerim connect --mode mcpconfig writers for Codex CLI, Claude Code, Cursor, OpenCode, Gemini CLI, Cline, Claude Desktop, OpenClaw, Hermes, Goose, Roo Code, Kilo Code, Windsurf, and OpenHuman, with dry-run, backup, and verification support. - Added a native pi JSONL session adapter for
~/.pi/agent/sessions/. - Added generic trace submission and retry plumbing for JSONL, JSON arrays,
message wrappers, and plain-text transcripts through
lerim trace importand MCPlerim_trace_submit. - Added public benchmark scripts, raw artifacts, generated reports, and docs for LongMemEval-S retrieval, context budget, retrieval latency, MCP integration, trace-ingestion cost/performance, and aggregate extraction diagnostics.
- Added public integration docs, source-session context compiler docs, MCP versus native-adapter boundary docs, custom trace examples, and a commercial boundary document.
- Moved the core project metadata, license text, and contribution guidance to Apache-2.0.
- Reworked retrieval indexing to store compact public records plus hidden source-session index text, then rank with weighted reciprocal-rank fusion over semantic and lexical signals.
- Updated README and docs to position Lerim as a source-session context compiler for agent workflows, not only coding-agent memory.
- Updated MCP client config generation to use an absolute Python executable with
-m lerim.mcp_server, avoiding client startup failures whenlerimis not on the MCP client'sPATH. - Split benchmark documentation into Lerim-only results and market-wide comparison pages, with source/provenance boundaries for competitor rows.
- Hardened generic trace loading so empty trace files fail clearly instead of flowing into extraction.
- Preserved validated supporting record IDs in
lerim answeroutput so CLI and MCP users get explicitSources: rec_...evidence pointers. - Corrected support wording so MCP config support is not presented as native completed-session capture.
- Removed stale public launch visuals and regenerated current public/private release assets from checked source assets and transcripts.
- Hardened release workflows with strict docs build, clean/tracked public
benchmark validation, PEP 517 build,
twine check, clean install checks, and MCP stdio probes before publishing.
- Added custom trace-folder projects with
lerim project add <path> --type custom. - Added direct custom JSONL session discovery with
agent_type=custom, without platform adapters or compaction. - Added custom-agent integration docs with a pasteable cleaner prompt for generating customer-owned trace cleaning scripts.
- Added per-agent architecture docs with Mermaid flowcharts generated from the compiled LangGraph graphs.
- Added integration coverage that registers a custom project, writes synthetic traces, runs ingest, and verifies custom sessions/jobs use the original clean trace files.
- Updated README, docs, bundled skill text, and configuration reference around the broader context-compiler positioning and custom-agent trace flow.
- Extended project config/API/CLI payloads with
supportedandcustomsource types while preserving existing project defaults.
- Expanded Lerim from a coding-agent memory layer into a general trace-to-context architecture for AI agent workflows.
- Added BAML/LangGraph context curation, context answering, and context-brief compilation alongside trace ingestion.
- Added layered durable-signal filtering, source-session review, synthesized record updates, and a final context quality gate.
- Added integration coverage for each BAML-backed agent role with real LLM calls.
- Renamed the live agent roles around the new context architecture: trace ingestion, durable-signal filtering, context writing, context curation, context answering, and context-brief compilation.
- Refreshed prompts to avoid fixture-specific or coding-only assumptions and to classify durable signal from broader agent activity traces.
- Updated README, docs, bundled skill text, and landing-page positioning around agent traces, durable signal, and future-agent context.
- Hardened SQLite migrations for foreign-key-safe table rebuilds.
- Tightened answerer retrieval so topical words are not misread as record-kind filters.
- Improved context-brief validation by dropping unsupported generated lines before rendering.
- Removed the remaining PydanticAI agent runtime and retired fallback/dead configuration paths.
- Packaged the BAML source and generated client under
src/lerim/agents/so future agents can share the same BAML/LangGraph layout. - Added the production BAML/LangGraph extract package with deterministic trace windowing, typed BAML scans, record synthesis, context-store persistence, and structured graph events.
- Replaced sync extraction with the BAML/LangGraph harness while keeping maintain, ask, and working-memory on PydanticAI.
- Updated extraction evals, integration tests, docs, and run artifacts to use graph events instead of PydanticAI extract messages.
- Tuned extraction prompts to avoid storing incidental personal names unless identity itself is the durable context.
- Hardened session catalog/API status paths so catalog storage issues degrade status responses instead of crashing status or maintain.
- Made extraction persistence idempotent when a rebuilt session catalog replays a session whose episode already exists.
- Improved long-running extraction queue handling so transient SQLite heartbeat write failures and sequential processing do not create false stale-running jobs.
- Removed the legacy PydanticAI extract agent, extract-only trace tools, history processors, and the experimental
baml_agents/sidecar.
- Unit docs-contract tests no longer require a repo-local
AGENTS.md; the authoritative agent tool contract check now only reads committed public docs.
- Local-first context runtime built around the canonical SQLite context store, project-scoped records, version history, FTS, and local embedding-backed retrieval.
- Semantic agent toolsets for sync, maintain, and ask flows, including context listing, search, fetching, writing, revising, archiving, superseding, counting, trace-note, and pruning tools.
- End-to-end MLflow observability for sync, maintain, and ask runs using Lerim-owned root/tool/event spans that continue through controlled PydanticAI retries.
- Expanded runtime artifacts, queue/status metadata, Docker runtime helpers, and CLI/API coverage for context operations.
- Larger unit, smoke, integration, and end-to-end test suites for context extraction, maintenance, retrieval, queueing, cloud sync, scope handling, and CLI behavior.
- Reworked memory terminology and docs around durable context records instead of legacy per-project markdown memory files.
- Updated provider, tracing, configuration, logging, and run-artifact behavior for the DB-backed context architecture.
- Refreshed README and documentation for setup, commands, storage layout, context model, tracing, and operational workflows.
- Release-readiness cleanup for provider fallback parsing, strict TOML string/path validation, SPDX license metadata, and docs accuracy around sync ordering, tracing, semantic search config, and query sessions.
- MLflow traces now preserve a successful Lerim root run even when a tool attempt raises a controlled retry before later recovery.
- CI
unit-testspipeline now passes again after restoring missing test compatibility helperbuild_test_ctxinlerim.agents.tools. - Addressed Ruff failures in unit tests (unused imports and ambiguous loop variable names), so release branches no longer fail lint before tests run.
- Kept queue project filter fallback behavior while removing unused exception binding in API path resolution.
lerim status --livenow uses the same data and renderer as snapshot mode, with periodic refresh only as the difference.- New status payload fields for richer operations visibility:
projects[]per-project memory/queue/blocker summaryrecent_activity[]timeline includingsyncandmaintainunscoped_sessionstotals by agent
- New
lerim unscopedcommand to inspect indexed sessions that do not map to a registered project. - Queue filters now support exact project matching (
--project) and explicit substring matching (--project-like).
- Status UI redesigned for clarity:
- project stream table (
blocked/running/queued/healthy) - explicit “What These Terms Mean” section
- actionable “What To Do Next” section with full
lerim ...commands - activity panel (sync + maintain)
- project stream table (
- Read/query defaults now use all registered projects unless explicitly narrowed:
lerim status --scope all|project --project ...lerim ask --scope all|project --project ...lerim query records list --scope all|project --project ...
- Canonical run telemetry is now written in
service_runs.details_jsonwith normalized keys (metrics_version=1, sync/maintain totals, per-project metrics, events) while preserving legacy compatibility fields.
- Live status activity no longer appears stale during long in-flight sync runs; running queue jobs are now surfaced in
recent_activity. - Fixed maintain runtime error (
name 'index_path' is not defined) that caused maintain runs to fail.
- +41% composite quality score via Layer 1 AutoResearch optimization
- ChainOfThought for the prior extraction pipeline (biggest single improvement)
- Explicit dedup classification thresholds (0.7/0.4) in sync prompt
- Improved MemoryCandidate schema field descriptions for better output consistency
- Tighter post-extraction body filter (30→50 chars minimum)
- 4 new eval runners: dedup accuracy, maintain quality, search relevance (NDCG@5), tool selection
- LerimBench 7-dimension composite scoring with configurable weights
- Fuzzy title matching for dedup accuracy (substring + Jaccard similarity)
- Golden dataset support via
--golden-dirflag - Deterministic extraction and summarization assertion checkers
- Local bundled dashboard removed — web UI moving to https://lerim.dev
lerim dashboardshows transition message with CLI alternatives- API server remains for Docker container health checks
- Removed stale Codex tool references from ask prompt
- Cleaned up stale OAI SDK / ResponsesProxy references in internal docs
- Removed PydanticAI dependency -- all agent operations now use a ReAct runtime.
- Removed explorer subagent — replaced by Codex filesystem sub-agent.
- Removed custom filesystem tools (read, write, edit, glob, grep) — Codex handles all filesystem ops.
- Removed
[roles.explorer]config section (kept in default.toml for compatibility but unused).
- ReAct runtime with a provider-agnostic LM wrapper for multi-provider support (MiniMax, ZAI, OpenRouter, OpenAI, Ollama, MLX).
- Codex tool as intelligent filesystem sub-agent with kernel-level sandboxing.
- Unified
providers.py-- all providers use the same LM wrapper path (no proxy layer needed). - Cross-session intelligence in maintain: signal amplification, contradiction detection, gap detection.
- Cross-agent knowledge synthesis: detects patterns across Claude, Cursor, Codex, OpenCode sessions.
- Context curation with Active Decisions, Key Learnings, Recent Context, and Watch Out sections.
- Memory outcome field (worked/failed/unknown) for feedback tracking.
- Docker container hardening: read_only root, cap_drop ALL, seccomp profile, mount only .lerim/ dirs.
- Dashboard Intelligence tab: memory health score, contradictions, signals, gaps, cross-agent insights.
- Server readiness check on
lerim up:cli.pynow polls/api/healthfor up to 30 seconds after starting the container, printing a clear warning if the server never responds. pytest-timeoutadded to the[test]optional dependency group for controlled test execution time.MINIMAX_API_KEYadded to the environment-variable look-up list in the HTTP API.
- Docker dashboard path:
dashboard.pyresolves the dashboard directory correctly inside containers by falling back to/opt/lerim/dashboardwhen the repo-relative path does not exist. A correspondingCOPY dashboard/step is added to theDockerfile. - Test
pythonpath:[tool.pytest.ini_options]now includespythonpath = ["."]sofrom tests.helpers import ...resolves when runninguv run pytest. - HTTP API key list:
_API_KEY_ENV_NAMESis sorted alphabetically and now includesANTHROPIC_API_KEYandMINIMAX_API_KEY.
- Parallelism support: three config knobs control concurrent execution:
max_workersin[roles.extract]: parallel extraction window processing via ThreadPoolExecutor (each thread gets its own LM instance for thread safety).max_explorersin[roles.explorer]: concurrent explorer subagent calls per lead turn.parallel_pipelinesin[server]: run extract + summarize pipelines in the same tool turn.
- Async explore tool: explorer subagent changed from sync (
run_sync) to async (await agent.run), enabling true concurrent dispatch via PydanticAI'sasyncio.create_task. - Adaptive prompts: sync and maintain prompts now emit parallel or sequential instructions based on config values. Set knobs to
1/falsefor local models.
max_workersfrom[roles.summarize]— summarization uses sequential refine/fold, so window parallelism does not apply.
- Ollama lifecycle management: automatic model load/unload around sync and maintain cycles. Models are warm-loaded into GPU/RAM before each cycle and unloaded after (
keep_alive: 0) to free 5-10 GB of memory between runs. Controlled byauto_unload = truein[providers]. - Proxy bridge support: new proxy provider base URL in
[providers]for routing PydanticAI OpenAI-format calls to Ollama's native API (enables thinking mode control). - Eval framework: four eval pipelines (
extraction,summarization,sync,maintain) with LLM-as-judge scoring, config-driven model comparison, andbench_models.shmulti-model benchmarking script. - Eval configs for Ollama models (Qwen3.5 4B/9B, thinking/non-thinking) and MiniMax-M2.5 cloud baseline.
- Synthetic eval traces and judge prompt templates for all four pipelines.
evals/compare.pyfor cross-config result comparison.lerim skill installcommand to copy skill files into agent directories.
- Docker networking: generated
docker-compose.ymlnow includesextra_hosts: host.docker.internal:host-gatewayso containers can reach Ollama running on the host.
- Evals folder reorganized: active configs moved to
evals/configs/, stale MLX configs removed. - Default provider switched to MiniMax-M2.5 with Z.AI fallback.
- Daemon loop: maintain never triggered on startup in Docker containers where
time.monotonic()reflected VM uptime smaller than the maintain interval (60 min). - Daemon loop: sync/maintain cycles produced zero log output, making
lerim logsappear idle. Added per-cycle status logging. - Session queue: NULL
repo_pathjobs clogged the claim queue, preventing valid sessions from being extracted. Added filter inclaim_session_jobsand guard inenqueue_session_job. - DB migration: orphaned NULL
repo_pathpending/failed jobs are now purged on schema init. - Explorer subagent: switched from structured
ExplorerEnvelopeoutput to plainstrto avoid repeated output-validation failures with models that return empty responses after tool calls. - Explorer failures no longer crash the lead agent; the
exploretool returns empty evidence and logs a warning. - Maintain action path validation: handle list-valued
source_path/target_pathfrom LLM output (model sometimes returns multiple paths per action). run_maintain_oncenow accepts atriggerparameter instead of hardcoding"manual"for all service-run records.
- Per-run LLM cost tracking via OpenRouter's
usage.costresponse field. Cost (USD) logged inactivity.logand returned in sync/maintain/ask result payloads. - Chronological (oldest-first) session processing for correct memory ordering.
- Structured context-writing tool replaces raw file writes.
_process_claimed_jobsruns sequentially (was parallel) for chronological memory consistency.- Activity log format now includes cost column.
- Docker service architecture: always-on daemon + HTTP API + dashboard in a single container.
lerim initinteractive setup wizard for first-time configuration.lerim project add/list/removefor incremental project registration.lerim up/down/logsfor Docker container lifecycle management.lerim servecommand — combined HTTP API + dashboard + daemon loop (Docker entrypoint, also usable directly without Docker).- Service commands (
ask,sync,maintain,status) are thin HTTP clients that talk to the running server. - HTTP API:
/api/health,/api/ask,/api/sync,/api/maintain,/api/status,/api/connect,/api/project/*. [agents],[projects], and[providers]config sections inconfig.toml.- Provider API base URLs configurable via
[providers]section (no more hardcoded URLs). Dockerfilewith Python 3.12, health check,lerim serveentrypoint.- Same-path volume mounting for zero path translation between host and container.
- Continual learning layer for coding agents and projects.
- Platform adapters for Claude Code, Codex CLI, Cursor, and OpenCode.
- Memory extraction pipeline using ChainOfThought with transcript windowing to extract decisions and learnings from coding session traces.
- Trace summarization pipeline using ChainOfThought with transcript windowing to produce structured summaries.
- PydanticAI lead agent with a read-only explorer subagent for memory operations.
- Three CLI flows:
sync(extract, summarize, write memories),maintain(merge, archive, decay), andask(query memories). - Daemon mode for continuous sync and maintain loop.
- Local read-only web dashboard with HTTP API.
- Session catalog with SQLite FTS5 for session search.
- Job queue with stale job reclamation.
- TOML-layered configuration: shipped defaults, global, project, and env var override.
- OpenTelemetry tracing via Logfire with PydanticAI and runtime instrumentation.
- Multi-provider LLM support: OpenRouter (with Nebius routing), Ollama, ZAI, OpenAI, Anthropic.
- SQLite-backed context model for durable records and derived indexes.
- Project-scoped context records in the global context DB.
- Context record kinds: decisions, facts, procedures, preferences, and episodes.
- Comprehensive test suite with 290 tests across unit, smoke, integration, and e2e layers.
- Skills distribution via
npx skills add lerim-dev/lerim.