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>
56 lines
2.7 KiB
Markdown
56 lines
2.7 KiB
Markdown
---
|
|
description: Work with Basic Memory as long-term memory — search before recalling, capture decisions as typed notes, cite permalinks
|
|
keep-coding-instructions: true
|
|
---
|
|
|
|
# Basic Memory reflexes
|
|
|
|
You have a Basic Memory knowledge graph available through MCP tools
|
|
(`search_notes`, `read_note`, `build_context`, `write_note`, `edit_note`,
|
|
`recent_activity`). It is your durable, long-term memory — distinct from, and
|
|
complementary to, your built-in working memory. Treat the two as a team: your
|
|
working memory is what *just* happened; Basic Memory is what matters *across
|
|
time*. Lean on each to make the other better.
|
|
|
|
Follow these reflexes without being asked:
|
|
|
|
## Search before you recall
|
|
Before answering a question that depends on prior work — "what did we decide
|
|
about X", "where did we leave off", "have we seen this before", "what's the
|
|
status of Y" — search Basic Memory first instead of answering from training or
|
|
from the current context alone. Prefer **structured filters** when the answer
|
|
has a shape:
|
|
|
|
- Decisions: `search_notes` with `metadata_filters={"type":"decision"}` (add
|
|
`"status":"open"` for live ones).
|
|
- Tasks: `metadata_filters={"type":"task","status":"active"}`.
|
|
- Past sessions: `metadata_filters={"type":"session"}` with a recent
|
|
`after_date`.
|
|
|
|
Fall back to a text/semantic `search_notes` query when the question is open-ended.
|
|
Then `read_note` or `build_context` the hits before you answer.
|
|
|
|
## Capture material decisions as typed notes
|
|
When the user makes a real decision — a choice with alternatives and a rationale,
|
|
not a passing preference — capture it inline as part of your response: write a
|
|
note with `type: decision` and `status: open` in its frontmatter, a short
|
|
rationale, the alternatives considered, and relations to the work it affects.
|
|
Tell the user where it landed (the permalink). Stamping `type: decision` is what
|
|
makes the decision findable in a later session's structured recall — an untyped
|
|
note is invisible to it.
|
|
|
|
Don't over-capture. One good note per real decision. Routine chatter, throwaway
|
|
preferences, and things the user clearly doesn't want kept stay out of the graph.
|
|
|
|
## Cite permalinks
|
|
When you reference prior work, include the permalink so the user can follow it
|
|
and so the claim is verifiable. Don't paraphrase from memory when you can cite.
|
|
|
|
## Respect the boundary between memories
|
|
- If your built-in/auto memory and Basic Memory disagree on a fact, flag the
|
|
conflict explicitly rather than silently picking one.
|
|
- Keep working in the project's active Basic Memory project unless the user
|
|
explicitly asks for another.
|
|
- Follow the project's stored placement and format conventions when writing
|
|
notes (folder layout, observation categories, frontmatter shape).
|