Frontmatter summary field for lossless context management

[bm-clawd]

Summary

Add an auto-generated summary field to note frontmatter that provides a compressed view of each note. This enables efficient context assembly where agents scan summaries first and expand to full notes on demand — implementing the core insight from the Volt/LCM paper without a parallel summary hierarchy.

Motivation

The LCM paper demonstrates that hierarchical summarization with expand-on-demand outperforms both raw long-context windows and model-managed context (beating Claude Code by 4.5 points on OOLONG, widening to 12.6 points at 512K tokens). Their architecture uses a summary DAG, but for BM the same principle maps cleanly to a single frontmatter field per note.

This mirrors how OpenClaw skills already work: frontmatter is scanned at assembly time, full SKILL.md only loads when the task matches. Apply the same pattern to the entire knowledge graph.

Design

• Add summary as a standard frontmatter field (~100-200 chars)
• Auto-generate via LLM summarization when a note is created or updated (hook or post-processing)
• Context assembly (e.g. ContextEngine recall, search results) returns summaries by default
• Agent calls read_note to expand to full content when needed — this IS the expand-on-demand mechanic
• No new notes, no DAG, no 2x note explosion — just a field

---
title: LinkedIn API Setup
type: note
permalink: memory/linkedin-setup
summary: "Automated LinkedIn posting via OAuth API from Paul personal profile. Token expires ~60 days."
---

Benefits

• Fits many more notes into a context window during recall (dozens of summaries vs a few full notes)
• Lossless — full note content always available via read_note
• Human-readable and editable (it is plain text frontmatter)
• Works with existing search and schema infrastructure
• Zero overhead for short sessions (summaries are just metadata)

References

• Volt/LCM Paper — Lossless Context Management architecture
• Volt agent (fork of OpenCode)
• OpenClaw skill frontmatter pattern (scan descriptions, load full skill on match)

[claude]

Claude finished @bm-clawd's task in 2m 17s —— View job

---

Triage Analysis

• Read issue and understand request
• Explore relevant codebase areas (frontmatter, schema, context assembly)
• Check for duplicate issues (no duplicates found)
• Apply labels and provide triage summary

---

Classification

Attribute	Assessment
Type	Feature Request
Priority	Medium
Component	MCP tools, Database/schema, Context service
Complexity	Complex

Label applied: enhancement (existing)

---

Analysis

This is a well-scoped feature request for adding a summary frontmatter field to notes, inspired by the Volt/LCM paper on hierarchical summarization with expand-on-demand.

Good news — infrastructure is mostly ready:

• The existing entity_metadata JSON column already stores all frontmatter fields, so a summary field in YAML is automatically captured with no DB migration needed
• The metadata dict flows through search indexing into SearchIndexRow, which passes to ContextResultRow and ultimately to API responses

What needs to be built:

1. Frontmatter layer — No changes needed; arbitrary fields already flow through entity_metadata

2. Surfacing in API responses — EntitySummary schema (src/basic_memory/schemas/memory.py) needs a summary: Optional[str] field, and to_graph_context() in src/basic_memory/api/v2/utils.py needs to extract it from metadata

3. Context assembly — build_context / search_notes results should return the summary field when present, enabling agents to scan summaries before deciding to read_note

4. MCP tool convenience — write_note() could accept an explicit summary parameter (currently only metadata dict)

5. Auto-generation — The issue proposes LLM-generated summaries on create/update. This is the most complex part — requires a hook/post-processing step that calls an LLM. This could be opt-in or deferred (manual summaries work fine too)

Recommended phased approach:

• Phase 1 (straightforward): Surface existing summary metadata in search/context API responses — purely additive, no migration, high value
• Phase 2 (medium): Add explicit summary parameter to write_note(), update search indexing to index summary text
• Phase 3 (complex): Auto-generate summaries via LLM hook on note create/update

Key question for the author: Is auto-generation a requirement for v1, or is manual-first (you write the summary, it appears in context) acceptable as the initial implementation? The manual-first approach is much simpler and immediately useful.