mirror of
https://github.com/basicmachines-co/basic-memory
synced 2026-06-21 13:47:35 +00:00
Paul Hernandez
5458c35b35
Signed-off-by: phernandez <paul@basicmachines.co> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
103 lines
4.8 KiB
Markdown
103 lines
4.8 KiB
Markdown
# Why combine Basic Memory with Claude's built-in memory
|
|
|
|
Claude Code already has memory — auto-memory, the short notes Claude keeps to itself
|
|
per project. So why add Basic Memory on top?
|
|
|
|
Because they're built for different jobs, and **the best setup uses both**. That's not
|
|
our marketing line — it's the [documented stance](https://docs.basicmemory.com/concepts/vs-built-in-memory)
|
|
of Basic Memory itself:
|
|
|
|
> "Basic Memory doesn't replace them — it works alongside them. The best setup uses both."
|
|
|
|
This plugin is the piece that makes "use both" happen automatically, instead of making
|
|
you copy context back and forth by hand.
|
|
|
|
## Two memories, two jobs
|
|
|
|
| | Claude's working memory | Basic Memory |
|
|
|--|------------------------|--------------|
|
|
| **Like** | RAM — what just happened | A journal — what matters over time |
|
|
| **Holds** | build commands, debugging tips, recent patterns | decisions, research, meeting notes, project context |
|
|
| **Scope** | one project, local, invisible | cross-project, portable, syncable, **sharable** |
|
|
| **Search** | whatever's in the window | semantic + structured (by `type`, `status`, …) |
|
|
| **Lifecycle** | summarized, compacted, eventually lost | durable Markdown files you own |
|
|
|
|
Working memory is fast and automatic but shallow and disposable. Basic Memory is
|
|
deliberate, structured, and permanent. Neither is "better" — they compound.
|
|
|
|
## 1 + 1 = 3
|
|
|
|
The multiplier is what each makes possible *for the other*:
|
|
|
|
- Working memory knows you were "in the auth refactor." Basic Memory turns that into a
|
|
**briefing**: the open decisions, the active tasks, the note where you rejected the
|
|
single-token approach last week — with permalinks.
|
|
- When the context window compacts, working memory compresses and loses detail. The
|
|
plugin has already written a **durable checkpoint** to Basic Memory, so the next
|
|
session resumes with the thread intact.
|
|
- Working memory can't be searched, linked, or shared. Basic Memory can — so a decision
|
|
you capture today is findable in three weeks, from another repo, or by a teammate.
|
|
|
|
Each session starts richer than the last. The graph is the part that accumulates.
|
|
|
|
## Who it's for
|
|
|
|
### The thinker — non-developer power user
|
|
Writers, researchers, consultants, planners who live in Claude (Code or Desktop), keep
|
|
a body of work that compounds over months, and don't touch git.
|
|
|
|
> *"What did we conclude about the pricing model?"* — Claude searches the graph and
|
|
> answers with the actual note, not a guess. A month of conversations stays one
|
|
> `search_notes` away.
|
|
|
|
**Wins:** picking up where you left off; never losing the texture of a long session;
|
|
recalling what you actually decided.
|
|
|
|
### The builder — developer
|
|
Uses git and GitHub, runs Claude Code as the primary pairing partner, works across
|
|
multiple repos.
|
|
|
|
> A multi-hour debugging session hits compaction. Instead of Claude "forgetting" what
|
|
> you already ruled out, the checkpoint records the dead-ends — so it doesn't suggest
|
|
> the thing that already failed.
|
|
|
|
**Wins:** decisions tied to the work; surviving long sessions without amnesia; code
|
|
archaeology weeks later (*why did we do it this way?*).
|
|
|
|
### The operator — PM, team lead, ops
|
|
Runs several projects through Claude, lives in decisions and status more than code,
|
|
often on a **team**.
|
|
|
|
> First session on a teammate's project: the SessionStart brief already shows the
|
|
> team's recent open decisions. You're oriented before you ask a single question.
|
|
|
|
**Wins:** no context bleeding between projects; team memory that compounds across
|
|
people; sharing a decision to the team in one gesture (`/basic-memory:bm-share`).
|
|
|
|
## What you actually get
|
|
|
|
Once installed and set up (`/basic-memory:bm-setup`):
|
|
|
|
- **Session briefings** — start each session knowing your active tasks, open decisions,
|
|
and (if on a team) recent team context.
|
|
- **Checkpoints that survive compaction** — long sessions don't lose their thread.
|
|
- **Capture reflexes** — Claude searches before answering recall questions and writes
|
|
down real decisions as it goes, citing permalinks.
|
|
- **Quick capture** — `/basic-memory:bm-remember` for a fast note without breaking flow.
|
|
- **Team memory** — read across shared projects; publish back deliberately.
|
|
|
|
All of it in plain Markdown files you own, in projects you control — local, cloud, or
|
|
both.
|
|
|
|
## What it deliberately does *not* do
|
|
|
|
- It doesn't replace Claude's auto-memory or fight it — they run side by side.
|
|
- It doesn't capture *everything*. Auto-memory already handles the running summary;
|
|
Basic Memory is for what's worth keeping. The plugin captures decisions and
|
|
checkpoints, not every turn.
|
|
- It never auto-writes to a shared team project. Capture stays personal; sharing is a
|
|
deliberate, confirmed gesture.
|
|
|
|
See [getting-started.md](./getting-started.md) to set it up, or
|
|
[architecture.md](./architecture.md) for how it works under the hood.
|