mirror of
https://github.com/basicmachines-co/basic-memory
synced 2026-06-21 13:47:35 +00:00
phernandez
3ff40d51fc
Reframes the Claude Code plugin as the bridge between Claude's working
memory and Basic Memory's durable graph, per plugins/claude-code/DESIGN.md.
This is the minimal-first vertical slice with a clean break from v0.3.x.
Added:
- hooks/session-start.sh — SessionStart brief: one structured `type: task`
query against the configured (or default) project + always-on recall
prompt. Plain stdout, silent if BM is absent.
- hooks/pre-compact.sh — PreCompact checkpoint: writes a `type: session`
note before compaction (extractive). Only writes when primaryProject is
set, so it never touches an un-opted-in graph.
- output-styles/basic-memory.md — capture reflexes (search-first, typed
decision notes, cite permalinks); keep-coding-instructions: true.
- schemas/{session,decision,task}.md — picoschema seeds (validation: warn)
so plugin-written notes are findable via metadata_filters. task mirrors
the memory-tasks skill.
- settings.example.json — copyable config with sensible defaults.
Removed (clean break):
- the six bundled skills, the basic-memory-manager agent, the
PreToolUse/PostToolUse write_note hooks, the basic-memory config-note
convention, and PLUGIN.md. Equivalent workflows live in top-level skills/.
Other:
- Rewrote scripts/validate_claude_plugin.py for the new layout (hooks +
output-style + schemas; agent dropped; skills optional). Passes
`just package-check-claude-code` incl. `claude plugin validate --strict`.
- Rewrote README around the bridge story; updated CHANGELOG, marketplace
descriptions, and the AGENTS.md package-check note.
- Hooks tested end-to-end against throwaway projects (brief surfaces tasks;
checkpoint writes a queryable session note; both degrade silently).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>
49 lines
2.0 KiB
Markdown
49 lines
2.0 KiB
Markdown
---
|
|
title: Session
|
|
type: schema
|
|
entity: Session
|
|
version: 1
|
|
schema:
|
|
summary?: string, one-paragraph what-happened this session
|
|
context?(array): string, key context needed to resume after memory loss
|
|
next_step?(array): string, explicit cursor for the next session
|
|
decision?(array): string, decisions surfaced during the session
|
|
problem?(array): string, problems hit — including attempted-and-rejected approaches
|
|
produced?(array): Entity, notes created or updated during the session
|
|
settings:
|
|
validation: warn
|
|
frontmatter:
|
|
project: string, the Basic Memory project this session belongs to
|
|
started: string, when the session began (ISO timestamp)
|
|
ended?: string, when the session was checkpointed
|
|
status?(enum, lifecycle of the checkpoint): [open, resumed, closed]
|
|
cwd?: string, the working directory the session ran in
|
|
claude_session_id?: string, Claude Code session identifier
|
|
capture?(enum, how this checkpoint was produced): [extractive, summarized]
|
|
---
|
|
|
|
# Session
|
|
|
|
A **SessionNote** is a resume checkpoint written by the Basic Memory plugin's
|
|
PreCompact hook (and, later, the `/basic-memory:handoff` command) right before
|
|
Claude Code compacts the context window. It records what the session was doing
|
|
so the next session can pick up where this one left off.
|
|
|
|
Sessions are found by the SessionStart hook via structured recall:
|
|
`search_notes(metadata_filters={"type": "session"}, after_date="3d")`.
|
|
|
|
## What goes in a SessionNote
|
|
|
|
- **summary** — a short paragraph of what happened (richer once summarized
|
|
checkpoints replace the extractive first cut).
|
|
- **context** / **next_step** — the cursor: what's in flight and what to do next.
|
|
- **decision** / **problem** — choices made and dead-ends hit, so the next
|
|
session doesn't repeat them.
|
|
- **produced** — relations to the notes this session created or changed.
|
|
|
|
## Frontmatter
|
|
|
|
`type: session` and `status` are the queryable fields that power recall. `warn`
|
|
validation means a missing field is surfaced, never blocking — the user's flow
|
|
is never gated on schema conformance.
|