David F GliddenandClaude Opus 4.8
3f9a89b00c
Basic Memory v0.21.6 first sync over the live memory dir (steward-authorized live-dir trial, Option A 2026-06-06): adds permalink: to frontmatter, refolds long YAML description lines, strips final newlines. Bodies untouched — verified via full diff classification. From this commit forward, any diff in claude/memory shows only what Basic Memory or the session writes. Trial design: MemPalace untouched as incumbent; git status check on this dir at every wrap; end-of-day evaluation (recall quality, sync robustness, rebuild-from-files, malformed-file behavior). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
88 lines
4.4 KiB
Markdown
88 lines
4.4 KiB
Markdown
---
|
|
name: Design Brief — Session Start/End Agents
|
|
description: Design problem for session lifecycle agents that replace manual memory
|
|
maintenance with source-of-truth reconciliation
|
|
type: project
|
|
permalink: claude-memory/design-brief-session-agents
|
|
---
|
|
|
|
# Design Brief: Session Lifecycle Agents
|
|
|
|
**Date:** 2026-04-02
|
|
**Status:** Design problem — next session
|
|
**Why:** Memory files went stale 3+ times in a single productive session. Manual sync is unsustainable and error-prone. The session handoff hook is static text that never updates itself.
|
|
|
|
---
|
|
|
|
## Problem Statement
|
|
|
|
State about the collaboration lives in too many places, updated at different times, by different actors (steward, executor, jurist, hooks). No mechanism reconciles them. When memory files drift from reality, the executor either works from stale context or burns time syncing — both are waste.
|
|
|
|
## Constraint: What Memory Should Store
|
|
|
|
Only things that **cannot be derived from artifacts**:
|
|
- Steward preferences and feedback
|
|
- Decisions and their rationale (the *why*, not the *what*)
|
|
- Personal context (schedule, collaborators, relationships)
|
|
- Reference pointers (where to look, not what's there)
|
|
- Cross-project context that no single repo captures
|
|
|
|
Everything else should be **queried at session start** from authoritative sources.
|
|
|
|
## Authoritative Sources (query, don't store)
|
|
|
|
| Information | Source of truth | How to query |
|
|
|---|---|---|
|
|
| What code changed | `git log` across repos | Git CLI |
|
|
| Finding/task status | FINDINGS.md, PENDING.md, REVIEWED.md | Read file, parse status fields |
|
|
| BMF health | `curl localhost:3011/health` | HTTP |
|
|
| What's in the registry | Registry files on disk | Read files |
|
|
| Ollama models | `ollama list` | CLI |
|
|
| Repo structure | File system | Glob/Read |
|
|
|
|
## Candidate Approaches
|
|
|
|
### A — Startup query agent + session-end diff agent
|
|
|
|
**Startup:** Agent reads authoritative sources, compares against last known state (stored in a lightweight `session-state.json`), reports what changed. No manual memory to maintain for derived state.
|
|
|
|
**Session end:** Agent diffs current state against session start, captures: decisions made, tasks completed, things left incomplete, blockers discovered. Writes a structured handoff (not prose — structured data the startup agent can consume).
|
|
|
|
**Pro:** Clean separation. Memory files shrink to non-derivable context only.
|
|
**Con:** Two agents to maintain. Startup agent needs to know all sources.
|
|
|
|
### B — Single reconciliation agent on a loop
|
|
|
|
Agent runs periodically (every N minutes or on significant events) and keeps a single state file current. Session start reads it; session end is just the last reconciliation.
|
|
|
|
**Pro:** Always current, no end-of-session rush.
|
|
**Con:** Background cost. May be noisy. Harder to distinguish "what changed this session" from "what changed since last check."
|
|
|
|
### C — Hook-driven incremental updates
|
|
|
|
Post-commit hooks, post-tool-use hooks update specific state fields. No agent — just targeted updates wired to events.
|
|
|
|
**Pro:** Minimal overhead. Updates happen at the moment of change.
|
|
**Con:** Hooks are fragile. Can't capture decisions that don't produce commits. Doesn't handle cross-repo state.
|
|
|
|
### D — Hybrid: hooks for fast updates + agent for reconciliation
|
|
|
|
Hooks handle the obvious updates (commit → task done, health check → BMF status). Agent runs at session start and end to catch what hooks missed and reconcile drift.
|
|
|
|
**Pro:** Best of both. Hooks keep things warm; agent catches drift.
|
|
**Con:** Most complex to build and maintain.
|
|
|
|
## Design Questions for Next Session
|
|
|
|
1. Which approach fits the actual workflow? (David works in bursts, sometimes rapid-fire decisions, sometimes long gaps between sessions)
|
|
2. What format should the handoff take? (Structured data the agent consumes? Prose the human reads? Both?)
|
|
3. Should the three-party model's decisions (steward authorizations, jurist reviews) have their own tracking mechanism separate from task status?
|
|
4. How much startup time is acceptable? (If the agent reads 5 repos + health endpoint + 3 status files, that's 10-15 seconds)
|
|
5. Should this integrate with the existing hooks system or replace the session handoff hook?
|
|
|
|
## What NOT to Build
|
|
|
|
- A dashboard or monitoring UI — this is a CLI collaboration
|
|
- A database — files and git are the persistence layer
|
|
- Anything that requires BMF to be running — it's currently down and shouldn't be a dependency
|
|
- Anything that duplicates what `git log` already does |