There’s a particular friction when an AI assistant forgets everything between sessions. You explain your setup once. Again the next day. A third time when you switch projects. The assistant doesn’t remember your laptop’s quirks, your dev environment, or decisions you made last week — so every interaction starts from zero.
I got tired of it. So I wired in persistent memory.
This is Part 6 of 6 in the Building a Private Local-AI Stack series.
- The Use Case
- LightRAG as a Personal Knowledge Base
- OpenRouter and the Case for Safe Models
- Right-Sizing a Local LLM with llmfit
- AionUi: A GUI for Your CLI AI Agents
- Basic Memory: An AI Memory in My Obsidian Vault (this post)
What basic-memory Actually Is
The Obsidian knowledge graph visualization of my AI assistant’s memory — plain Markdown notes stored directly in my vault. Source: jamescroft.co.uk
basic-memory is an MCP server that gives an AI assistant genuine long-term memory. It’s wired into opencode (the agent CLI I use), but works with any MCP-compatible client.
The storage format is dead simple: plain Markdown files, one note per entity. Each note has a title, structured metadata, and then observations (individual facts) and relations (links to other entities). It’s not a database or vector store. Just notes with a tiny bit of structure.
The magic is where those notes live: directly in my Obsidian vault, synced across devices with Syncthing. The Markdown files are the source of truth. There’s a local search index for fast queries, but it’s disposable — rebuilt from Markdown anytime something changes.
How It Works in Practice
At session start, the assistant runs a quick restore: it reads my user profile, checks recent activity, searches for anything relevant to the current topic. If I’m working on a specific project, it already knows the architecture decisions, gotchas, and commands that matter.
During the session — and always at the end — it saves durable facts. A preference. A decision. A quirk of my laptop’s environment. Those get written as new notes or appended to existing ones. Next time, that context is already there.
It’s the difference between “tell me about your setup” every time and “I see you’re still using that custom Docker network config — want me to account for that?”
Why This Matters More Than I Expected
The accuracy improvement is real. The assistant stops making assumptions that were wrong three sessions ago. It remembers I’m on Fedora, not Ubuntu. It knows my Hugo blog deploys via Google Cloud Build. It doesn’t suggest solutions that require tools I don’t have.
But the bigger shift is transparency. Every hosted assistant has memory now — longer context windows, threads persist, some claim long-term recall. But you can’t see what they “know” about you. You can’t correct it when it’s wrong or audit what’s stored.
With basic-memory, I can. The memory is Markdown in my vault. If the assistant misremembers, I open the note and fix it. If I want to know what it knows about a project, I search. If I want to delete something, I delete the file. The AI doesn’t own my context — I do.
What Gets Remembered (and Why Markdown Wins)
The system doesn’t try to remember everything. It stores three kinds of things:
Facts about me and my environment. My dev setup. Laptop quirks. Preferences for commit style, directory structures, file naming. Anything that doesn’t change often but gets referenced constantly.
Project-specific knowledge. Architecture decisions. Gotchas we’ve hit. Commands that matter. The context that makes the assistant useful on a codebase.
Durable decisions. If we spend half an hour working through a design question and land on an approach, that decision gets saved. Next time a similar question comes up, the assistant already knows what we chose and why.
The assistant decides what’s worth saving, and I can override. The default behavior is solid: it saves what matters and skips noise.
Storing memory as Markdown has benefits I didn’t appreciate until I’d been using it:
Git-friendly. Markdown diffs cleanly. I can version-control the assistant’s memory. git diff shows what changed between sessions.
Human-readable. No proprietary formats or binary blobs. Just text files I can open in any editor. If the assistant writes something confusing, I can read it. If wrong, I can fix it.
Editable without breaking things. Because Markdown is source of truth and the search index is disposable, I can edit notes directly without worrying about schema mismatches or index corruption. Change a note, the index rebuilds. That’s it.
Portable. If I ever stop using basic-memory, the notes are still useful. They’re just notes in my vault. They don’t become vendor-locked junk.
The Relationship with LightRAG
If you read Part 2, you’ll remember LightRAG — the semantic query layer over my entire document corpus. That’s the big read-only memory: thousands of documents indexed for retrieval, used when I need to pull in knowledge from past work.
basic-memory is different. It’s the small, curated write store. It’s not trying to index everything I’ve written. It’s storing facts and decisions that need to persist between sessions.
LightRAG is the research library. basic-memory is the notebook you carry.
What It Doesn’t Do
basic-memory is not a RAG system. It doesn’t do vector search or embeddings. It’s not a “second brain” surfacing related knowledge from across your corpus.
It’s a small, fast, structured memory layer for the assistant to store and retrieve facts. If you need semantic search over thousands of documents, you want LightRAG. If you need the assistant to remember your name and dev environment, you want basic-memory.
It also doesn’t try to be invisible. The assistant explicitly says when it’s saving or loading context. I like that. I want to know when memory is being written, and I want to be able to say “don’t save that.”
The Syncthing Piece
Because the memory lives in my Obsidian vault, and my vault syncs across devices with Syncthing, the assistant’s memory syncs too. If I have a session on my laptop then switch to my desktop, context carries over. If I edit a note in Obsidian on my phone, the assistant sees the change next load.
This wasn’t planned. It’s what happens when you store memory as plain files in a directory that’s already synced. But it’s quietly useful.
What I’d Change
It’s not perfect. The system works well for storing facts and decisions, but it’s not great at forgetting. Once something gets saved, it tends to stay unless I manually delete it. That’s fine for durable facts, but memory can accumulate noise if I’m not periodically cleaning it up.
I’d also like better tooling for reviewing what’s been saved. Right now, I can search my vault or browse the notes directory, but there’s no “show me everything the assistant knows about this project” command.
Still — those are refinements. The core idea works. The assistant remembers what matters, stores it transparently, stops making me repeat myself. That’s the goal, and it delivers.
The Real Benefit
The first time I started a session and the assistant already knew my environment, my project, and decisions I’d made last week — without me saying a word — it clicked. This is what persistent memory should feel like. Not a black box. Not a vendor-locked service I can’t inspect. Just notes in my vault, structured enough to be useful, transparent enough to be trustworthy.
It remembers. I can see what it remembers. When it’s wrong, I can fix it.