There’s a particular kind of friction that builds up when you work with an AI assistant that forgets everything between sessions. You explain your setup once. Then again the next day. Then a third time when you switch projects. The assistant doesn’t remember your laptop’s quirks, your dev environment, or the decisions you made last week — so every interaction starts from zero, and you spend half your time re-explaining context that should already be there.
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
basic-memory is an MCP server — a small piece of infrastructure that gives an AI assistant genuine long-term memory. It’s wired into opencode (the agent CLI I use), but it works with any MCP-compatible client.
The storage format is dead simple: plain Markdown files, one note per entity. Each note has a title, some structured metadata, and then observations (individual facts) and relations (links to other entities). It’s not a database. It’s not a vector store. It’s just notes with a tiny bit of structure on top.
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 on top for fast queries, but it’s disposable — it gets rebuilt from the Markdown anytime something changes. The memory is just notes I can open, read, and edit like anything else in my vault.
How It Works in Practice
At the start of every session, the assistant runs a quick restore: it reads my user profile, checks recent activity, and searches for anything relevant to the current topic. If I’m working on a specific project, it already knows the architecture decisions we made, the gotchas we’ve hit, and the commands that matter.
During the session — and always at the end — it saves durable facts. A preference I stated. A decision we made. A quirk of my laptop’s environment. Those get written as new notes or appended to existing ones. Next time I start a session, 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, not Netlify. It doesn’t suggest solutions that require tools I don’t have installed.
But the bigger shift is transparency.
Every hosted assistant has some kind of memory now — context windows are longer, threads persist, some services even claim long-term recall. But you can’t see what they “know” about you. You can’t correct it when it’s wrong. You can’t audit what’s being stored or delete a fact that shouldn’t be there.
With basic-memory, I can. The memory is just Markdown files in my vault. If the assistant misremembers something, I open the note and fix it. If I want to know what it knows about a project, I search my vault. If I want to delete something, I delete the file. The AI doesn’t own my context — I do.
What Gets Remembered
The system doesn’t try to remember everything. It’s not an append-only log of the entire conversation. It stores three kinds of things:
Facts about me and my environment. My dev setup. The quirks of my laptop. My preferences for commit message style, directory structures, or file naming conventions. Anything that doesn’t change often but gets referenced constantly.
Project-specific knowledge. Architecture decisions. Gotchas we’ve hit and fixed. Commands that matter. The kind of context that makes the assistant useful on a codebase instead of just generically helpful.
Durable decisions. If we spend half an hour working through a design question and land on a specific approach, that decision gets saved. Next time a similar question comes up, the assistant already knows what we chose and why.
None of this is automatic. The assistant decides what’s worth saving, and I can always override it. But the default behavior is solid: it saves the things that actually matter and skips the noise.
The Relationship with LightRAG
If you read Part 2 of this series, you’ll remember LightRAG — the semantic query layer that sits on top of 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 ever written. It’s storing the facts and decisions that need to persist between sessions so the assistant doesn’t forget who I am or what we’re working on.
Think of it this way: LightRAG is the research library. basic-memory is the notebook you carry with you.
The Plain Markdown Advantage
Storing memory as Markdown has a few benefits I didn’t fully appreciate until I’d been using it for a while.
Git-friendly. Markdown diffs cleanly. If I want to version-control my assistant’s memory, I can. If I want to see what changed between two sessions, git diff works.
Human-readable. No proprietary formats. No binary blobs. Just text files I can open in any editor. If the assistant writes something confusing, I can read it. If it writes something wrong, I can fix it.
Editable without breaking things. Because the Markdown is the 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, and the index rebuilds itself. 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.
What It Doesn’t Do
basic-memory is not a RAG system. It doesn’t do vector search. It doesn’t have embeddings. It’s not trying to be a “second brain” that surfaces related knowledge from across your entire 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 your dev environment, you want basic-memory.
It also doesn’t try to be invisible. The assistant explicitly says when it’s saving something 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” if it’s about to store something I’d rather it forget.
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 and then switch to my desktop, the context carries over. If I edit a note in Obsidian on my phone, the assistant sees the change the next time it loads.
This wasn’t a planned feature. It’s just what happens when you store memory as plain files in a directory that’s already synced. But it’s quietly useful. The assistant’s memory of me is as available as the rest of my notes, everywhere I work.
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 saved unless I manually delete it. That’s fine for durable facts, but it means the memory can accumulate noise over time 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 just browse the notes directory, but there’s no “show me everything the assistant knows about this project” command. It’s all in there, but surfacing it takes manual work.
Still — those are refinements. The core idea works. The assistant remembers what matters, stores it transparently, and stops making me repeat myself every session. That’s the goal, and it delivers.
The Real Benefit
The first time you start a session and the assistant already knows your environment, your project, and the decisions you made last week — without you saying a word — it clicks. This is what persistent memory should feel like. Not a black box. Not a vendor-locked service you can’t inspect. Just notes in your vault, structured enough to be useful, transparent enough to be trustworthy.
It remembers. You can see what it remembers. And when it’s wrong, you can fix it.
That’s the difference.