feat(v0.2.0): intent-anchor reframe — new schema, event-driven writes, tighter injection#1
Merged
Merged
Conversation
Two independent AI sessions used memento in production across extended,
multi-compaction workloads and wrote detailed post-session reviews. This
commit addresses every finding, validated by a fresh-eyes audit and a
deep-think optimization pass before implementation.
Behavioral enforcement (highest-impact changes):
- SKILL.md: add CRITICAL write section as first content — highest-attention
position ensures the journal write instruction competes better under load
- SKILL.md: post-compaction + no-prior-journal case now handled explicitly —
recovering sessions with existing context must create the journal immediately,
not wait for a user request
- SKILL.md: minimal 6-field first-write template — reduces friction of the
first Write call, the highest-risk moment in any session
- tracker: source-aware "no prior journal" hint — compact/resume source gets
urgency language; startup gets "BEFORE first task" framing
- tracker: closed-mission prompt — when mission_closed is set, emit an active
reminder to open a new mission instead of going silent
- tracker: staleness-aware reminders — if the last completed entry is >30 min
old and mission is active, escalate reminder with "last task N min ago"
language. Self-correcting: a journal write resets the timestamp.
Schema and consistency fixes:
- tracker + SKILL.md: set state:'waiting', state_reason:'mission complete'
when closing a mission — both the hook (/clear path) and Claude-driven
closure now produce consistent state
- config: two-tier staleness — closed missions collapse at STALE_DAYS (7d);
active missions at 2× (14d) to protect journals during extended breaks
- config: raise MAX_COMPLETED default 8→12, add MEMENTO_MAX_ENTRIES env var
(range 4–24) — covers a typical 2-4 hour session fully at negligible cost
- config: cross-project noise suppression — when the journal belongs to a
different, closed project, suppress detailed completed entries and emit a
one-line summary instead of irrelevant task history
New SKILL.md guidance:
- Recovery: journal the verification step as a completed entry after compaction
- Recovery: WORK_STATE.md coexistence — treat it as authoritative for task
specifics, use both sources
- Mission: append execution constraints to mission field ("fix X -- user: don't Y")
giving a recovering Claude behavioral context, not just task direction
- Project: proj:default fallback — update to first directory worked in
- Rolling window: document two-tier staleness model
README accuracy:
- Token overhead: correct "under 400 tokens" to "under 2,000 tokens total"
(journal injection ~400, SKILL.md spec ~1,500 loaded once per session)
- Write visibility: honest disclosure — journal writes appear in tool stream,
hook output is invisible
- Add "How Reliable Is It?" section — honest framing with manual fallback
- Add memory layer guidance — when to use memento vs MEMORY.md vs CLAUDE.md
- Feature ctx typed prefixes and in_progress more prominently
- Configuration table: add MEMENTO_MAX_ENTRIES, MEMENTO_STALE_DAYS staleness
model note, MEMENTO_INSTANCE_TAG shared-account callout
Housekeeping:
- gitignore: add docs/feedback/ for AI session review files (may contain
internal project references; stored locally only)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- closed mission now emits prior-mission-closed reminder (was: no output) - stale collapse threshold bumped 10→15 days (active missions collapse at STALE_DAYS*2=14d) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Core changes: - Mission field: verbatim capture format (400 chars, was 200), includes request + constraints + done-when for true intent preservation - completed/upcoming/in_progress/state/state_reason → done/plan/wip - done entries: task → act; wip is a plain string (not an object) - Write cadence: event-driven (5 triggers) instead of after every task - MAX_COMPLETED 12→6, MAX_UPCOMING 5→3 - summarizeEntries now preserves ctx content (forward causation) in collapse - Injection format: no footer paragraph; Plan: instead of Next: - Backward-compat: old journals read transparently, normalized on next write - stale-collapse bug resolved (state fields dropped entirely) - SKILL.md: full rewrite — wip string, plan, causal linkage, ctx note: examples, no discussion-mode special case, updated recovery section All 46 tests passing (31 utils + 15 hooks). +5 new tests, -2 removed (state tests). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- entryToSummaryLine now preserves ctx in rolling-window pruning path
(previously only stale-collapse path preserved ctx; now consistent)
- cross-project suppression no longer requires mission_closed; suppress
detail for any foreign-project journal regardless of mission status
- brief-mode + tracker reminder: reword from "after task completion" to
"when information that compaction would destroy changes" (matches
event-driven cadence in SKILL.md)
- SKILL.md: staleness thresholds now reference MEMENTO_STALE_DAYS
("default 7 days / 2× for active") instead of hardcoded numbers
- SKILL.md: replace internal us-seo example with generic DB-eval example
- SKILL.md: fix note: ctx example in recovery section — forward-causation
pattern only; omit ctx when result has no forward implication
46/46 tests passing.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Remove inaccurate "~1,500 tokens for SKILL.md" overhead claim — SKILL.md is ~4,500 tokens and is only loaded on explicit invocation, not auto-loaded per session. Actual per-session cost is ~350 tokens (recovery injection) or ~100 tokens (startup), confirmed by live measurement. Also update test count in session-validation.md to reflect 46 tests. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add explicit write trigger for exploratory/advisory sessions: when research produces meaningful progress but no discrete task completions, set wip to snapshot decision state (eliminated / candidates / open question). Fixes the coverage gap where research sessions were invisible to the journaling model. Also aligns README and SKILL.md language with the v0.2.0 event-driven model: replace "completes a task" with "information changes that compaction would destroy" in How It Works diagram; add research-state wip example to WIP tracking sections; update frontmatter description. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
done[](wascompleted[]),plan[](wasupcoming[]),wipstring (wasin_progressobject),actfield (wastask). Full backward-compat — old journals read transparentlystate,state_reason— replaced bywipstring with full context; removes known inconsistency bug where stale-collapse setmission_closedwithout updatingstateentryToSummaryLine()now preservesctxwhen folding into rolling summary — v0.1.x silently discarded causal chains at prune timejournal.project !== projectTag, regardless ofmission_closed— v0.1.x only suppressed closed missionsTest plan
bash tests/run.sh)completed/upcoming/task/in_progress/statefields read correctlyPlan:prefix, no footer,actfield, mission 400-char limit🤖 Generated with Claude Code