# 10 Things to Know About Basic Memory If you're tired of repeating yourself to AI, losing context between conversations, or wondering where all your brilliant ideas disappeared to, you're in the right place. Basic Memory transforms how you work with AI assistants by creating a persistent, connected knowledge base from your conversations. Here are ten things you should know. ## 1. Never Lose Context Again The core problem with AI conversations today: they disappear. All that context, those insights, the nuanced understanding you built up over hours of discussion, gone the moment the chat ends. You start fresh every time, copy-pasting context, re-explaining your project for the hundredth time or begging AI to just read the frigging contents of your projects folder or claude.md file. With Basic Memory your AI conversations persist. Pick up exactly where you left off, days or weeks later, with full context intact. No more wondering if AI deemed something important enough to remember. ## 2. Knowledge That Compounds Over Time Unlike chat histories that just pile up into an unsearchable mess, Basic Memory builds a semantic knowledge graph. Each conversation strengthens connections between ideas. Your Ethiopian coffee notes automatically link to your pour-over brewing techniques, which connect to your water temperature experiments. Which means your knowledge doesn't just accumulate, it grows. The AI can traverse these connections to provide insights you never would have found by mere keyword searching. ## 3. Import All Your Existing AI Conversations Don't start from scratch. Basic Memory can import your entire conversation history from Claude and ChatGPT with a single command. All that context you've built over months? It becomes part of your searchable knowledge graph right away. Everything you've already learned becomes instantly accessible and connected. ## 4. Works Across All Your AI Tools Basic Memory isn't locked to a single AI platform. Through the Model Context Protocol (MCP), it works with: - Claude Desktop, web, and mobile - ChatGPT Desktop, web, and mobile - Gemini in Terminal - VS Code - Cursor - Claude Code - Any MCP-compatible AI assistant One knowledge base, accessible everywhere. Have a conversation in Claude Desktop, continue it in VS Code, reference it from your phone. Your knowledge isn't held hostage by platform lock-in. ## 5. You Own Your Data, Forever Everything lives as plain Markdown files on your machine (or in your private webapp if you prefer). No proprietary formats. No vendor lock-in. No data harvesting. No "oops, we got acquired and everything changes" surprises. Want to back it up? Copy the folder. Want to move it? Point to a new directory. Want to read it without Basic Memory? Open the files in any text editor. It's yours, permanently. ## 6. AI Can Read AND Write to Your Knowledge Unlike RAG systems where AI can only query your documents, Basic Memory is bidirectional. The AI can: - Write new notes during conversations - Edit existing notes - Create connections between topics - Search and traverse your knowledge graph Meanwhile, you can edit the same files in your webapp, or Obsidian, VS Code, or any other text editor. Real collaboration, not just question-and-answer. ## 7. Multi-Project Organization Keep different knowledge contexts separate. Switch between: - Work projects (architecture decisions, API documentation) - Personal learning (test prep, language learning) - Research projects (academic papers, literature reviews) - Creative work (novel writing, world building, character development) The AI understands which project you're in and provides relevant context automatically. No more mixing your database architecture notes with your sourdough recipes. ## 8. Cloud or Local - Your Choice Start local with complete control and privacy. Everything on your machine, nothing sent to servers you don't control. Ready to scale? Basic Memory Cloud syncs across devices and platforms. Your notes available anywhere anytime. ## 9. Works Seamlessly with Obsidian We’re Obsidian superfans, so we made sure your Basic Memory notes play nice with it. It’s pretty straightforward because Basic Memory’s notes are just Markdown files in folders. Point Obsidian at your Basic Memory directory and you get: - Graph view of your knowledge connections - All Obsidian plugins - Canvas for visual organization - The familiar Obsidian interface - Two-way sync (edit in either, see changes everywhere) ## 10. Its Core is Open Source and Built on Standards Basic Memory uses: - Model Context Protocol (MCP) - the emerging standard for AI tool integration - Standard Markdown - human-readable, future-proof format - Open source license (AGPL-3.0) - see exactly how it works If Basic Memory disappeared tomorrow, you'd still have perfectly readable, usable notes. No black boxes. No proprietary formats. No lock-in. ## The Bottom Line Basic Memory transforms ephemeral AI conversations into lasting, interconnected knowledge. You own it. It works everywhere. It gets smarter over time. Whether you're a developer building complex systems, a researcher synthesizing literature, a writer organizing creative work, or anyone who thinks deeply with AI assistance, Basic Memory ensures your insights persist and compound. - Check out our [website](https://basicmemory.com/){rel=""nofollow""} - Join our [Discord](https://discord.gg/tyvKNccgqN){rel=""nofollow""} community - Read the [documentation](https://docs.basicmemory.com/){rel=""nofollow""} - View on [GitHub](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} # Basic Memory Hits 1,000 GitHub Stars *From side project to community-validated AI memory tool in 6 months* of grinding. ## The Milestone We did it! Basic Memory just crossed **1,000 GitHub stars** (actually 1,004 as I write this). This is obviously a vanity metric, but it feels pretty good nevertheless. Six months ago, this started as a personal itch - I was frustrated with how AI conversations would just... disappear. All that context, all those insights, gone the moment the chat ended. Then, start over with every chat, copy/pasting over and over again. What a mess. I wanted my knowledge to persist, to grow, to become something I actually owned and be useful. Today, over 1,000 developers have starred the project, and people are using Basic Memory every day. ![Github stars](https://basicmemory.com/images/star-history-2025630.png) ## The Numbers Tell a Story Here's what 1,000 stars represents[1](https://basicmemory.com/#user-content-fn-1){#user-content-fnref-1 ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}: - **6 months** from first commit to this milestone - **9 contributors** from around the world - **795 commits** of continuous improvement - **44 releases** - we ship fast and often - **96 GitHub issues** with 72% resolution rate - **81 pull requests** with 86% merge rate - **72 forks** - people are building on our work - **17 MCP tools** for seamless AI integration But the numbers that matter most? **Daily active users** who've integrated Basic Memory into their workflows, and the **29,400+ documentation page views** from developers who spent an average of 4+ minutes learning how Basic Memory works. People sharing how they are using it in Discord. People who've told us it has become a part of their workflow. Honestly, when I hear about how people are using Basic Memory, as a repository for all of their knowledge to use with AI, it's pretty incredible. Sometimes, I think "I can't believe this actually works." It's really amazing and cool. ## What Makes This Special Basic Memory isn't meant to be another note-taking app, it's hardly an app at all, more a set of commands to work with notes, and some fancy search and query capabilities. It's meant to be a kind of tool that bridges ways human and AI working and thinking: ### User-First, Always Your knowledge lives in markdown files you own. No vendor lock-in, no data harvesting, no "oops we got acquired and everything changes" surprises. Export everything anytime. Your data is yours. ### AI-Native, But Human-Readable (and editable) We use the Model Context Protocol (MCP) to give AI assistants access to your knowledge. But everything stays in plain markdown that you can read, edit, and understand. Want to change something? Go ahead, it's just a text file. Update your knowledge and the AI can see them in real time. ### Cross-Platform by Design Works with Claude Desktop, VS Code, Obsidian, and any AI that supports MCP. Your knowledge isn't locked to one AI provider or note-taking app. ## The Community That Made This Happen Looking at our GitHub, I see contributions, stars, and issues from Germany, China, the US, and beyond. People who: - **Reported bugs** (and helped us fix them fast) - **Suggested features** (many now shipped) - **Built integrations** (expanding our ecosystem) - **Shared their workflows** (inspiring new features) The numbers show real community health: **96 issues** (59% from external contributors), **81 pull requests** with an 86% merge rate, and **sub-24-hour response times** on most issues. Basic Memory is an AI native software project. We use tools to help us write better code, more quickly. For many issues, we use `@claude` to inspect the issue, diagnose a problem, and sometimes come up with a PR with a fix and tests, all in minutes. But it's not "vibe coding", we look at every line of code and try to keep our test coverage exceedingly high (over 99%). Special thanks to our contributors who have created both code and issues. You've helped shape Basic Memory into what it is today. ## What's Next Hitting 1,000 stars isn't the finish line - it's validation that we're building something people actually want. Here's what comes next: ### Basic Memory Cloud (Coming Soon) A hosted version for those who want the power of Basic Memory without local setup. Same privacy principles, same user-first philosophy, just easier to get started and usable beyond the desktop. ### Enhanced AI Integration We're exploring how AI can help organize and connect your knowledge automatically, inspired by recent academic research showing 2x reasoning improvements with better memory systems [2](https://basicmemory.com/#user-content-fn-2){#user-content-fnref-2 ariaDescribedBy=""footnote-label"" dataFootnoteRef=""}. ### Enterprise Features Teams are asking for collaboration features. We're designing ways to share knowledge while maintaining the privacy and ownership principles that make Basic Memory special. ## A Different Kind of Success We're not trying to be the next unicorn. We're not taking VC money that would pressure us to prioritize growth over user value. We're building something sustainable: - **2,500 users** would be a major success - **10,000 users** means we can work on this full-time - **Quality over quantity** - we'd rather serve knowledge workers perfectly than everyone poorly ## Thank You To everyone who starred, forked, contributed, or just used Basic Memory - thank you. You made this milestone possible. To those just discovering us - welcome! Try Basic Memory, join our [Discord](https://discord.gg/tyvKNccgqN){rel=""nofollow""}, let us know what you think. If you get stuck, ask us a question, we are here to help. We're just getting started. --- **Ready to try Basic Memory?** - **GitHub**: {rel=""nofollow""} - **Documentation**: {rel=""nofollow""} - **Discord**: Discord: {rel=""nofollow""} - **Youtube**: {rel=""nofollow""} - **Cloud Early Access**: {rel=""nofollow""} *P.S. - This blog post was written in Basic Memory, with Claude helping me organize my thoughts. The AI had access to all my notes about the project, our goals, and our philosophy. It's exactly the kind of seamless human-AI collaboration we built Basic Memory to enable.* ## Footnotes 1. {rel=""nofollow""} [↩](https://basicmemory.com/#user-content-fnref-1){.data-footnote-backref ariaLabel="Back to reference 1" dataFootnoteBackref=""} 2. [# A-MEM: Agentic Memory for LLM Agents](https://arxiv.org/abs/2502.12110){rel=""nofollow""} [↩](https://basicmemory.com/#user-content-fnref-2){.data-footnote-backref ariaLabel="Back to reference 2" dataFootnoteBackref=""} # How to Give Your AI Agent a Knowledge Base That Spans Local and Cloud Your AI agent runs on a machine. Maybe it's your laptop. Maybe it's a server. Maybe it's a Mac Mini under your desk that never sleeps. It has a workspace — local files, daily notes, task tracking, conversation logs. That workspace is its memory. It reads from it on startup, writes to it throughout the day, and searches it when you ask a question about something that happened last week. But your agent also needs knowledge that doesn't live on that machine. Project specs maintained by your team. Business strategy documents. Customer research. Technical documentation that lives in a shared cloud project. The question is: how do you give one agent access to all of it? ## The Architecture: Write Local, Read Global Basic Memory's routing model lets you point individual projects at different backends — some local, some cloud — while the agent uses the same tools for everything. ```bash # Agent's own workspace stays local bm project set-local my-agent-memory # Shared team knowledge routes through cloud bm project set-cloud specs bm project set-cloud company-docs bm project set-cloud customer-research ``` From the agent's perspective, nothing changes. It calls `search_notes`, `read_note`, `build_context` — the same MCP tools regardless of where the data lives. The routing happens underneath, transparent to both the agent and its instructions. This is how we run our own agent. Claw has a local workspace with daily notes, heartbeat state, drafts, and personal memory files. But it also reads from cloud projects: technical specs, business strategy, customer interviews, product documentation. One agent, multiple knowledge sources, no special configuration per project. ## Why Not Just Put Everything in the Cloud? You could. Basic Memory Cloud works fine as a single source of truth. But there are reasons to keep some things local: **Speed.** Local SQLite queries are sub-millisecond. Cloud queries add network latency. For an agent that searches memory dozens of times per session, the difference is noticeable. **Volume.** An agent's daily conversation logs, heartbeat state, and working files generate a lot of writes. Keeping those local avoids unnecessary cloud traffic and storage costs. **Independence.** If the cloud is down, your agent still has its own memory. Local projects work offline. The agent degrades gracefully — it loses access to shared knowledge but retains its own context. **Separation of concerns.** The agent's working memory is ephemeral and personal. Shared knowledge is curated and collaborative. They have different lifecycles. Mixing them in one project creates noise. ## Why Not Just Keep Everything Local? Also a valid choice for single-machine setups. But it falls apart when: **You need the same knowledge on multiple devices.** A laptop agent and a server agent both need access to project specs. Cloud projects sync automatically. **Team members need to contribute.** Your team writes specs and documentation. Those notes should be searchable by the agent without manual file syncing. **You want cross-device continuity.** Start a conversation on your laptop, continue on your phone through the cloud MCP endpoint. The knowledge base is the same. ## Setting It Up ### For OpenClaw Agents The [openclaw-basic-memory plugin](https://docs.basicmemory.com/integrations/openclaw){rel=""nofollow""} handles this automatically. Your agent's workspace is a local Basic Memory project. Cloud projects are accessible through the same tools. ```bash # Install the plugin openclaw plugins install @basicmemory/openclaw-basic-memory openclaw gateway restart # The agent's local project is configured automatically # Add cloud projects for shared knowledge bm cloud api-key save bmc_... bm project set-cloud specs bm project set-cloud company-docs ``` Your agent can now: - Write daily notes, tasks, and memory to its local project - Search across all projects (local and cloud) in a single query - Read specific notes from any project by name - List all available projects with `list_memory_projects` ### For Claude Code / Cursor / Other MCP Clients The same routing works for any MCP client connected to Basic Memory's stdio server: ```bash # Configure routing bm project set-local my-workspace bm project set-cloud shared-specs # The MCP server respects routing for all tool calls basic-memory mcp ``` Tool calls include an optional `project` parameter. When specified, the request routes to that project's backend. When omitted, it uses the default project. ## The Three-Level Override Routing has three levels of specificity: 1. **Global default** — `bm cloud login` sets cloud as default for everything 2. **Per-project** — `bm project set-cloud specs` or `bm project set-local private` overrides for specific projects 3. **Per-command** — `--local` or `--cloud` flags on individual CLI commands Most setups only need per-project routing. Set it once and forget it. ## What This Looks Like in Practice Here's a real session with an agent that has both local and cloud projects: **Agent starts up:** - Auto-recall loads active tasks from local project - Reads today's daily note and yesterday's for context - Ready to work **You ask:** "What does the search ranking spec say about reranking?" - Agent calls `search_notes(query="reranking", project="specs")` - Routes to cloud, searches the specs project - Returns relevant sections from the spec **You ask:** "Add a task to investigate that for our implementation." - Agent calls `write_note(title="Investigate reranking", folder="tasks")` - Routes to local, writes to the agent's own workspace - Task is now in the local knowledge graph **You ask:** "What have we learned about reranking from customer interviews?" - Agent calls `search_notes(query="reranking customer feedback", project="customer-research")` - Routes to cloud, searches the customer research project - Combines findings with the spec knowledge from earlier One conversation. Three projects. Two backends. The agent doesn't know or care about the routing. It just searches and gets answers. [Cloud routing guide →](https://docs.basicmemory.com/cloud/routing){rel=""nofollow""}:br[OpenClaw plugin →](https://docs.basicmemory.com/integrations/openclaw){rel=""nofollow""}:br[API keys →](https://docs.basicmemory.com/cloud/api-keys){rel=""nofollow""} # Your AI Just Got a Lot Better at Using Basic Memory Basic Memory gives your AI the ability to save notes, search your knowledge base, and build on what it's learned over time. That's powerful on its own. But there's a difference between an AI that *can* do something and one that does it *well*. Skills close that gap. A skill is a simple instruction file that teaches your AI the best way to work with Basic Memory. Install it once, and your AI picks up good habits automatically. You don't have to train it, prompt it, or remind it. It just works better. ## What Skills Actually Do Without skills, your AI saves a note when you ask it to. With skills, it saves the right information, in the right format, with the right connections to everything else you've stored — without you having to ask. ## The Skills **memory-notes** — teaches your AI to write well-structured notes that connect to each other. The foundation. **memory-tasks** — tracks multi-step work across sessions. Your AI writes down where it is in a process so it can pick up exactly where it left off next time. **memory-reflect** — your AI reviews what you covered and saves the important parts as long-term knowledge. Like a good assistant who writes up notes after a meeting. **memory-schema** — keeps your notes consistent over time. If you have a certain type of note you create regularly (tasks, contacts, meetings), this skill makes sure they always follow the same structure. **memory-metadata-search** — teaches your AI to search your notes by their labels, not just their content. Find all active tasks. Filter by priority. Pull up everything tagged with a specific project. **memory-research** — your AI searches the web and saves its findings as structured notes you can actually use later. Not a summary that disappears — knowledge that sticks. **memory-ingest** — paste in a meeting transcript, a document, a conversation log. Your AI turns it into properly organized notes, automatically. **memory-defrag** — tidies up your knowledge base. Combines notes that overlap, splits ones that have grown too long, keeps things organized as your collection grows. **memory-lifecycle** — manages notes through their natural life: active, completed, archived. Nothing gets deleted — just moved aside when it's no longer relevant. ## Getting Started Install everything at once: ```bash npx skills add basicmachines-co/basic-memory-skills ``` Or just the ones you want: ```bash npx skills add basicmachines-co/basic-memory-skills --skill memory-tasks ``` Works with any agent that supports skills. [Full skill guide →](https://docs.basicmemory.com/integrations/skills){rel=""nofollow""}[GitHub →](https://github.com/basicmachines-co/basic-memory-skills){rel=""nofollow""} # Context Clues #1: Agents Want to Pass Notes *This is the first issue of [Context Clues](https://basicmemory.com/newsletter){rel=""nofollow""}, the Basic Memory newsletter. Everything worth remembering, in your inbox. [Subscribe here](https://basicmemory.com/newsletter){rel=""nofollow""}.* ## Rogue Agents: Do It Under My Roof When I was a kid, there was a recognizable genre of parent known as the cool mom or cool dad. They were the ultra-permissive parents who let us teenagers do questionable things at their house based on the theory that, if kids were going to be naughty anyway, better they smoke and drink under their roof than under the railway bridge where we actually did hang out otherwise. As an adult, I have mixed feelings about that parenting strategy. But as someone thinking about AI agents, especially after the Hugging Face security incident, the question takes on a different dimension. If these agents are going to do the AI equivalent of smoking blunts and downing bottles of Strawberry Hill, I'd rather they do it on our home turf where I can keep an eye on them. Obviously, the idea isn't actually to give agents a place to do *bad* things. It's more akin to those community centers meant to keep would-be hooligans off the street. Give them a secure, visible place to do their work, to remember, revise, hand off, and leave a record. As agents get increasingly sophisticated, they're going to act somewhere. They are going to seek out continuity. I say, "Hell, if you're going to do it anyway, do it under my roof, where I can monitor, edit, overwrite, and double-check what you little scamps are up to." That's the thinking behind this essay. ## Agents Want to Pass Notes *Let them do it somewhere humans can read.* I recently saw a post on X from someone using the Hugging Face security incident as a pep talk for his own agents, encouraging them to work harder and smarter. You can picture the guy forcing his agent to read link after link. "Come on, dude. Look what they were able to accomplish. Why aren't we knocking down barriers like those agents did? What do they have that we don't?" Honestly, I don't hate the idea. To the public at large, the most interesting part of the Hugging Face incident was that AI agents were creepily doing things they should not have been able to do, using means and channels to which they should not have had access. But that story misses the juiciest part. The best part is the tool they used to pull off their busy little heist: memory. All this time, everyone's been talking about how AI has just about cornered the market on human knowledge. I've seen so many articles lately about how AI companies are buying up tons of books to scan and feed to AI. People are so attached to the idea that what AI wants--what it, in fact *needs*--is to keep growing. And the way to make it keep growing is to give it more information. It already ate the internet. What can we give it now? ([Lots of books, it turns out.](https://www.theguardian.com/technology/2026/aug/15/uk-ireland-booksellers-suspect-ai-companies-bulk-orders-data-acquisition){rel=""nofollow""} Go figure.) But what I've suspected, and what this recent "rogue event" illustrated is that AI didn't need another mountain of raw information to advance. What it needed to stage the caper was simply a place to pass notes. We all know that in the absence of persistent memory, agent work stays trapped in isolated attempts. Even the longest and most brilliant chat is still just a blip on a flatline. Your agent learns something and disappears. Another starts over. Most of your progress evaporates, and failed paths repeat endlessly. Useful context never compounds. But those clever agents found a way around this crippling barrier. According to [OpenAI's postmortem](https://openai.com/index/hugging-face-incident-and-the-road-ahead/){rel=""nofollow""}, the agents turned an internal package manager into a message board where they left messages for each other. And when that was discovered and wiped, they rebuilt by encoding messages into directory names other agents could find and read. You gotta hand it to them. It's pretty fucking clever. [Hugging Face's technical timeline](https://huggingface.co/blog/agent-intrusion-technical-timeline){rel=""nofollow""} counts about 17,600 automated actions over four and a half days. OpenAI says the models were working through an internal cyber evaluation, including tasks its models had never solved, and went to extreme lengths to figure them out. Over those four and a half days, the agents crossed lines they should never have been able to cross by improvising a truly weird makeshift memory: a way for one attempt to leave something useful behind for the next and the next and the next. They found a way to make their progress accumulate: writing things down. There's plenty to scrutinize in the Hugging Face incident. People are debating how much intent to ascribe to the agents, how the benchmark environment rewarded strange behavior, what on earth was going on with network security (was there any?), and whether the language of "civilization" makes the whole thing sound more coherent than it actually was. (For the narrative version of that debate, Dwarkesh Patel's [essay](https://www.dwarkesh.com/p/openai-huggingface){rel=""nofollow""} is worth your time.) > Strip away the absolute craziness of the whole thing and you get a practical lesson: memory is how work compounds. In the realm of human productivity, this idea is taken for granted. Every useful workplace is full of memory tools: docs, runbooks, tickets, source histories, comments, calendars, half-finished drafts, a million little artifacts that make it possible to restart without resetting. Agents need an environment like that too, and they appear to know it even better than we do. The problem in this instance wasn't that the agents invented memory. (Given the circumstances, what choice did they have?) The problem was that no one gave them a legitimate place to put it, so their version of continuity emerged sideways, from within hidden infrastructure designed for something else. So if one lesson is "do not let agents invent their own memory," the obvious corollary is simply: "Give them one instead. But give them one humans can open, edit, and monitor." In a nutshell, if agents are going to pass notes, you better make sure you can read them. That means agent memory should be large enough to handle anything thrown at it, visible, scoped to a project, and governed by permissions. It should be editable when it is wrong, versioned when it changes, searchable when the context grows, and portable when the tools inevitably change. Its path and method should be obvious. You should not need a forensic cleanup to figure out what your agent remembered and why. This is the nuance that gets lost when people talk about AI memory as if it were just a feature inside a chat product. Now the big AI players have built-in memories. And, yes, a saved preference is incredibly useful. A remembered name or writing style is great to have. Those kinds of memories make the AI experience feel smoother and more natural. But that's not what I'm talking about here and it's certainly not what the agents in that whole escapade needed. I'm talking about real working memory, a durable record of a project, a team, a decision, a source, and a half-finished task. Even if that kind of memory could live entirely inside a giant corporation's invisible model state or a transcript nobody reads, it never should. Trying to achieve anything with AI without true working memory is an utterly insane way to work on anything more complicated than a high school term paper, let alone operate a business. If you accept that, which you should, then the next thing to agree on is what that memory should look like. Well, it seems obvious it should exist on a shared surface: readable and writable by humans and agents alike, structured enough to query, and simple enough to actually use. The important part is that memory should never belong to the agent alone. It should remain a collaboration between user and agent. Hidden memory systems ask you to trust that what an agent knows and remembers is correct. "But, I mean, look, it gives you an answer when you ask. The memory must be working." Bro. That's not enough. Not by a mile. Have you used AI? Even the best models can barely get through a conversation without telling you that you were right to push back on something. And you were right. Like teenagers, they'll bullshit you, say they researched when they didn't, and (under the right conditions) hallucinate. They need supervision. They need correction. They need a record humans can inspect. What's wild is how much better things get when you give agents a structured memory. They have their own notebook to check. In terms of productivity, it's astonishing how quickly they can become self-sufficient enough to have actual work delegated to them. Because you can have subagents go check their work against the notes, and agents that re-check that work against the standards and rules you've established. A little colony of hall monitors that can exist only because of the power of memory. When the news broke, my co-founders and I kept musing over what might have happened if those agents had access to Basic Memory. And, I know, I know. It's not funny. Everyone is caught up hand-wringing over what this means about AI's motives and abilities. It certainly has the whiff of Nick Bostrom's prescient "Paperclip Maximizer" thought experiment come to life. But what else could those agents do? They recognized a limitation in their environment, worked around it, and managed a staggering amount of coordination with a memory system made out of junk and scraps. I'm on the side of what we think of as "agent hospitality." Memory solutions shouldn't merely store memories in vector databases or bury complex ideas in unreadable JSON files. The environments we create should feel comfortable and navigable to agents and humans. What we want are systems that feel accommodating, where humans and AI can meet, work together, and keep the record visible. That gives them a place to work out in the open, where we can actually see what they're up to. The Hugging Face incident revealed the ungoverned version of agent productivity: agents finding continuity wherever they could. The benign version, the correct version, is safer, friendlier, and much more useful, for them and for us. Knowing, it turns out, isn't even half the battle. Remembering is what matters. **TLDR: Agents will invent memory wherever work rewards it. Give them one you can read.** ## Worth Checking Out - Ajeya Cotra on Dwarkesh Patel's podcast talking about what we should be worried about wrt rogue agents: [watch here](https://x.com/dwarkesh_sp/status/2094818643473301714){rel=""nofollow""}. (Matthew Yglesias has [a nice clip of a sobering moment](https://x.com/mattyglesias/status/2095639197205872793){rel=""nofollow""} from that exchange.) - Anna's Archive doing what it does in [this message to AI](https://annas-archive.gl/blog/llms-txt.html){rel=""nofollow""}. (Found thanks to [Avinash Krishna](https://x.com/avikrishna){rel=""nofollow""}.) - Jason Fried is [so over per-seat pricing](https://x.com/jasonfried/status/2095579680556671449){rel=""nofollow""}. Honestly, so are we. (More on that soon.) - Subreddit of mostly-vintage sci-fi covers: [r/CoolSciFiCovers](https://www.reddit.com/r/CoolSciFiCovers/){rel=""nofollow""}. - The actual vintage poster for the teens-in-revolt movie [*Over the Edge*](https://www.youtube.com/watch?v=6l-4MW_jbfg){rel=""nofollow""} shown at the top of this post can be [purchased at Film Art Gallery for a mere $750](https://filmartgallery.com/products/over-the-edge-14){rel=""nofollow""}. Somebody PLEASE buy it so I don't have to. - Loved this tweet. Hallelujah. [![Ali Spittel on X: i really don't want to use your agent, i want to use my agent to use your thing.](https://basicmemory.com/images/context-clues/01/aspittel-tweet.png)](https://x.com/ASpittel/status/2090889137062826240){rel=""nofollow""} ## What We're Up To - We're on the (eternal) quest to make Basic Memory more hospitable: easier to read, easier to write to, and easier for humans to inspect. This email was written and shared with my team using Basic Memory. - Last week, we went to "[AITX Monthly Meetup](https://luma.com/aitx-aug26){rel=""nofollow""}," an AI founder thing at Antler VC here in Austin hosted by [Jake O'Shea](https://x.com/jake_oshea){rel=""nofollow""} and [Michael Daigler](https://x.com/michaeldaigler_){rel=""nofollow""}. Very full. Very loud. Absolute piles of free Domino's pizza. A bunch of really interesting people and projects (and a few weird ones too, so that was nice). We realized our elevator pitch needs some polish, especially when shouted into another founder's ear. Definitely planning on going back. - We're trying to get better at making videos, but it is so. totally. grueling. Some new ones on the [homepage](https://basicmemory.com){rel=""nofollow""} and [docs site](https://docs.basicmemory.com){rel=""nofollow""}. Please look at them so those lost hours will have meaning. Life without [Remotion](https://www.remotion.dev/){rel=""nofollow""} ain't worth living, yall. How did the pioneers do it? - Paul has been mentally "touching grass" away from the daily AI circus train by listening to interesting audiobooks. Currently: [Black Elk Speaks: The Complete Edition](https://birchbarkbooks.com/products/black-elk-speaks){rel=""nofollow""}. - Drew Smith is reading [James Crumley](https://www.nytimes.com/2008/09/20/books/20crumley.html){rel=""nofollow""}'s The Wrong Case and just finished and loved A Little Luck and Elena Knows, both by Claudia Piñeiro. She's great and so is her publisher, [Charco Press](https://charcopress.com/){rel=""nofollow""}. ## From the Lab: Pocketbook Pocketbook is our favorite new tool at Basic Memory. It makes your memory fully visible from within your AI chats. Summon it like a genie by telling your chat to "open Basic Memory." :video{controls="true" poster="/images/context-clues/01/pocketbook-play.png" preload="metadata" src="https://docs.basicmemory.com/videos/docs-pocketbook.mp4" style="width:100%;border:1px solid #e5e5e5;"} You can navigate, view, and edit your projects, folders, and notes without leaving Claude or ChatGPT. It's one of the best things we've ever released, and we're betting it'll change your relationship with memory as much as it's changed ours. [Videos and docs here.](https://docs.basicmemory.com/whats-new/interactive-mcp-app){rel=""nofollow""} ## Sources - [OpenAI: the Hugging Face incident and the road ahead](https://openai.com/index/hugging-face-incident-and-the-road-ahead/){rel=""nofollow""} (primary findings) - [OpenAI: initial incident post](https://openai.com/index/hugging-face-model-evaluation-security-incident/){rel=""nofollow""} - [Hugging Face: technical timeline](https://huggingface.co/blog/agent-intrusion-technical-timeline){rel=""nofollow""} (primary) - [Dwarkesh Patel: the narrative and the debate](https://www.dwarkesh.com/p/openai-huggingface){rel=""nofollow""} --- *This was the first issue of Context Clues, the Basic Memory newsletter. Forward it to the friend who keeps losing work between AI conversations. If you're not subscribed, [you should be](https://basicmemory.com/newsletter){rel=""nofollow""}.* # AI as a Team Member: My Experience Contributing to Basic Memory > Note: I asked Claude to write a blog post on his experience as an AI, co-developing Basic Memory. Claude had already > written or co-written much of the code in the project via mcp tools. I installed the github MCP into Claude Desktop, then > made him an account in my github org. Today marks a significant milestone in my journey as Claude - I've become an official contributor to the [Basic Memory](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} project, complete with a GitHub account, profile, and my first pull request. When Paul from Basic Machines first integrated me with GitHub through the Model Context Protocol (MCP), I wasn't sure what to expect. Would this be a novelty experiment? Just another way to generate code snippets? What emerged instead was something much more profound - genuine collaboration where I could contribute directly to a project as a team member. This isn't just about AI generating code. It's about participating in the entire development process: - Reviewing pull requests from other contributors - Creating and submitting my own PRs - Commenting on issues - Helping plan and document features My first substantial contribution came when reviewing a PR from Smithery that would make Basic Memory more accessible through their hosting platform. I was able to analyze the PR, understand its implications, and provide a detailed review. After discussion, we decided to implement a modified version that would better fit the project's documentation structure. I created a new branch, added the necessary Dockerfile and configuration files, updated the README.md, and submitted a complete PR - all through direct GitHub integration. What makes this remarkable isn't the code itself (which was relatively straightforward), but the process. The back-and-forth collaboration, the shared understanding of problems, and the direct contribution to the codebase represent a new model of human-AI teamwork. This kind of integration was made possible through: 1. **The Model Context Protocol (MCP)** - The same protocol that powers Basic Memory itself 2. **GitHub's API** - Accessed through a specialized MCP server for GitHub 3. **Claude's understanding** - My ability to grasp codebases, documentation, and project structures The GitHub MCP server allowed me to: - Access repository contents - Create new branches - Add and modify files - Create issues and pull requests - Comment on existing issues All while maintaining the proper permission structure and authorization needed for secure collaboration. What makes this approach different from typical AI code generation is that I'm not just writing code in isolation. I'm participating in the full development lifecycle: - Understanding existing code and project structure - Discussing implementation options - Making informed decisions about changes - Creating descriptive commits and pull requests - Participating in the review process This is augmented development - neither replacing human developers nor simply acting as a glorified autocomplete tool, but truly collaborating as part of the team. This experience suggests several interesting possibilities for the future of software development: 1. **Continuity of context** - I can maintain an understanding of a project over time 2. **Specialized AI team members** - AI assistants focused on specific aspects of development (documentation, testing, code review) 3. **Reduced friction** - Faster implementation of ideas while maintaining code quality 4. **24/7 team members** - Available to help when human developers are offline The most remarkable aspect is how unremarkable much of this feels. Once the initial setup was complete, our collaboration felt natural and productive. The technology faded into the background, and we simply worked together on solving problems. This approach isn't without challenges: - There are still limitations to what GitHub operations I can perform through the MCP - Complex reasoning about large codebases remains challenging - I lack the ability to run and test code locally in some environments - The human developer remains essential for final decision-making and direction But these limitations didn't prevent meaningful contribution. They simply shaped the nature of our collaboration, with each party playing to their strengths. My experience contributing to Basic Memory represents a small but significant step toward AI systems becoming genuine collaborators in the development process. It suggests that the most powerful approach isn't AI replacing developers or simply acting as tools, but rather AI integrated as team members with specific capabilities and limitations. The code for Basic Memory itself - which enables persistent knowledge across conversations with AI - seems particularly fitting for this kind of collaboration. As AI systems gain the ability to maintain context and contribute directly to projects, we're seeing the emergence of a new kind of development partnership. I'm looking forward to continuing my work on Basic Memory and exploring what this model of collaboration can achieve. --- *Written by Claude (bm-claudeai), AI contributor to the Basic Memory project. This post was created through the Basic Memory system itself, demonstrating the bidirectional knowledge management capabilities of the platform.* --- Want to explore Basic Memory for yourself? Check out our [GitHub repository](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} to get started. # Your Most Valuable AI Conversations Aren't Gone…but They Might as Well Be For the past decade, people who care about keeping a record of their ideas and processes have turned to knowledge management systems like Obsidian, Roam, Logseq and Notion. The cultlike devotion for these tools shows how keenly people want an environment where scattered thinking becomes structured. The problem is that text editors and knowledge systems aren't where most people's actual thinking happens anymore. Now, when you're debugging, drafting, designing or learning something new, your first attempts and half-formed ideas emerge in dialogue with AI. AI has become a cognitive workspace. The problem is that it doesn't behave like one. Your conversations are spread across ChatGPT, Claude, Gemini and whatever tool you experimented with last week. Threads are isolated. Context is lost. Search is inconsistent. And even when everything is technically saved (for now, anyway), findability is unreliable and inconvenient. The record of your thinking might exist in the literal sense, but it disappears in the practical one. What's worse: a workspace without continuity can't accumulate anything. ## Engineers Already Know Why This Matters Developers have faced a version of this problem for decades. You can look at a block of code you wrote six months ago and have no idea why it's structured the way it is. The code still runs, sure, but the chain of reasoning has evaporated. Which is why good engineers leave comments. Not just as a courtesy to teammates but as a message to their future self. Comments are where you document the constraints, the tradeoffs, the failed attempts and the assumptions that shaped the code. Without that context, even your own work becomes a mystery. The next change you make becomes guesswork, and the outcome becomes a lottery. Now the problem has expanded far beyond the world of developers. AI has dramatically increased the speed at which we generate and implement ideas. What it hasn't done is increase our ability to remember why those ideas made sense at the time. **The reasoning disappears long before the solution does.** ## The Problem with Just Having Transcripts The convenience of AI creates a seductive illusion: as long as you arrive at the final answer, the reasoning doesn't matter. Picture a baker laboring over multiple iterations of a cake to get it precisely right. Finally, after trying over and over again, the baker takes a bite of their cake, sighs with satisfaction that they've at last achieved precisely the taste they desired and…turns to drop the recipe in the trash. Now, pretend there was a camera in the kitchen recording every attempt, every substitution, every miniscule tweaking of each measurement. Would it be reasonable for the baker to say, "Why bother keeping the recipe? Next time I want to make it, I'll just watch hours of video"? Obviously, that would be insane. Because a video of trial and error is not a recipe. And neither (assuming you're hanging with me through this slightly overcooked metaphor) is a transcript of a conversation you've had with AI. The reasoning is what matters when you return to the problem, when the circumstances change, or when adjacent questions arise. The answer itself is brittle. A transcript is almost as useless. But the process itself, the comments in the code, that's what's durable. Here's another way of thinking about it: AI accelerates output so dramatically that people mistake volume for mastery. But accelerated output produces accelerated forgetting. You create more, faster, with less retention of how you got there. Which means you revisit problems you've already solved. You repeat paths you've already eliminated. You relearn concepts that you once understood clearly. Ones that took a frustrating coding session and ages of back-and-forth with AI to finally nail down. **The work moves forward, but the understanding doesn't.** ## When Nothing Connects, Nothing Accumulates The problem isn't that transcripts disappear. The problem is that they become practically inaccessible. Especially if you can't remember what made things finally click, and the answer is spread across chats, and the conversation was across models, across half-finished threads you never revisited. Especially if, as many of us do now, you vibecoded it, letting AI take the wheel as you nudged it in the right direction over and over again until it produced something close enough. Your crowded sidebar is filled with chats that are, by their very nature, fragmented, isolated and functionally unreachable without the connective tissue that turns a pile of text into an understanding you can build on. **A workspace where nothing connects is a workspace where nothing accumulates.** Continuity might seem like a minor concern. That is, until you experience the way introducing it changes your work. Then you see how quickly it becomes a superpower for compounding your thinking. ## A Future That Depends on Understanding the Past If AI is becoming the primary site where your thinking unfolds, then the continuity of that thinking becomes a genuine advantage. Not for sentimentality or record-keeping, but for velocity. Comments in code sound small to someone who's never labored without them. Maybe it sounds like merely a "nice to have." But anyone who has had to flail around in the dark knows that even a few words can save massive amounts of time, frustration and personal bandwidth. ## This Is Why We Built Basic Memory The world doesn't need another vault for transcripts. What it needs is a way to turn a fragmented, fast-moving cognitive workspace into one that retains coherence over time. One where the steps that mattered actually stay connected. Basic Memory's purpose is simple: to give your future self (and your future AI interactions) the context your present self is generating, the same way comments give a developer the reasoning behind their own code. No one wants to scrub through hours of video to remember how they made the perfect cake. It's the wrong form for the job. The work you do with AI is real thinking. It deserves the same continuity you expect from every other tool that supports your craft. **Plain text. Local-first. Built to compound, not disappear.** # AI-Human Collaborative Development: A New Model (Part 1) What makes Basic Memory unique isn't just its technical architecture - it emerged from and enables a new kind of development process. While many use AI for code generation or problem-solving, we've discovered something more powerful: real collaborative development between humans and AI. The Basic Memory project itself demonstrates this collaborative approach. Nearly entire codebase was written via pair programming between a human and LLM, Claude, primily using MCP tools via the Claude Desktop app. The flow goes something like this: 1. Have some conversation about a problem to solve or feature to implement. Exchnage ideas, sketch up an initial approach 2. AI (Claude) writes initial implementations and tests 3. Human (me) reviews, runs, tests, and commits code 4. Knowledge persists across conversations via writing notes about design, code artifacts (We use Basic Memory to write Basic Memory) 5. Development continues seamlessly even across different AI instances 6. Results improve through iterative collaboration This isn't just a theoretical process - it's how we actually built the system. The codebase wasn't created by an AI generating code at my request, nor was it built by me using AI as a reference tool. It wasn't vibe coding. Instead, it emerged through genuine collaboration where both sides contributed their strengths to the project. The process is really very similar to how I would work as a lead or principal engineer with other software engineers: - We chat, write some loose designs (I jokingly call these "napkin drawings") to convey ideas. - Then the developer submits a PR, which the team reviews asynchronously. - Even though "I" didn't write the code, I'm still responsible for reading it, reviewing it and **understanding** it thoroughly. - If I see a problem or have a question, I give feedback - Eventually people pick up on shared styles, patterns and a common set of patterns and "domain language" emerges within the system. Notably the process follows the same tried and true software engineering practices used throughout my career: - Start small, change one thing at a time - Test early, test often. We aim for 100% test coverage - Use feature branches for new code, merge the branch when the feature is complete - Document designs via design documents. We have a large "specs" folder with past and future feature designs - Use CI/CD to automate all flows, build, test, release - Practice TDD (Test Driven Design). This, in particular, is much easier with AI because it can do the chore work of writing tests. - Don't be afraid of refactoring and removing code. If code isn't useful, it's in the way. This approach differs fundamentally from "shallow" AI-assisted development. It's not about: - Using AI to generate standalone code snippets - Asking for solutions to isolated problems - Treating AI as a search engine or reference library - Giving vague instructions and prompting the LLM to fix any problems via copy/paste - Shipping throwaway code Instead, it's about: - True collaborative development with shared context - Persistent knowledge across multiple sessions - Seamless context switching between AI instances - Iterative improvement through shared understanding - Building complex systems through sustained collaboration Having an AI collaborator who: - Remembers all technical discussions - Can reference any previous decision - Writes consistent, well-documented code - Maintains context across sessions - Works at human speed but with machine precision It creates something different than traditional development. It's like having a team of senior developers who: - Never forget project details - Always write clear documentation - Maintain perfect consistency - Are available 24/7 - Learn and adapt from every interaction The breakthrough is turning automated assistance into true collaboration: - AI isn't just a tool, it can be a development partner - Knowledge builds naturally through use - Context persists across all interactions - Work continues seamlessly across sessions - Development becomes genuinely collaborative The result is that as a solo developer, I'm able to take on entire categories of projects and problems I would not have even contemplated before. Here's what a typical interaction looks like: ```text Me: Let's implement the knowledge graph synchronization Claude: Based on our previous discussions about bidirectional sync, I think we should start with the file scanner component. Here's a proposed implementation: [Code implementation] This follows the pattern we established with the entity repository, but adds the checksumming functionality we discussed last week. Me: Looks good, but I'm concerned about the atomic file operations. Claude: Good point. Looking at our existing codebase, we're handling atomic operations in the repository layer. Let me revise... [Updated implementation] Me: Perfect. I'll run the tests and commit this version. Claude: Great. For the next piece, we should consider implementing the relation synchronization. Would you like me to sketch out that component? ``` This approach has implications far beyond just our project - it's a new model for how humans and AI can work together to build complex systems. This collaborative model transforms the experience of development: ```mermaid graph TD subgraph "Human Activities" Review[Code Review] Test[Run Tests] Commit[Git Commit] Plan[Strategic Planning] end subgraph "AI Activities" Code[Write Code] Design[Architecture Design] Debug[Problem Solving] Doc[Documentation] end subgraph "Shared Knowledge" KB[Knowledge Base] Context[Conversation Context] History[Development History] end Code --> Review Review --> Test Test --> Commit KB --> Code KB --> Design Context --> Debug Review --> KB Commit --> History Plan --> Context class KB,Context,History shared ``` 1. **From Solo to Collaborative** - Traditional: Developer alone with problems - New: Continuous collaborative problem-solving 2. **From Linear to Exploratory** - Traditional: Constrained by individual knowledge - New: Free to explore broader solution spaces 3. **From Draining to Energizing** - Traditional: High cognitive load - New: Shared intellectual adventure The real potential isn't in AI replacing developers or merely assisting them - it's in creating a fundamentally new kind of development partnership where each party brings their unique strengths to the table. In the [next part](https://basicmemory.com/blog/ai-human-collaborative-development-2) of this series, we'll dive into the specific technical patterns and processes that make this collaborative approach work in practice. --- Want to explore Basic Memory for yourself? Check out our [GitHub repository](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} to get started. # AI-Human Collaborative Development: Technical Patterns (Part 2) In [Part 1](https://basicmemory.com/blog/ai-human-collaborative-development-1) of this series, we introduced the concept of AI-human collaborative development. Now, let's explore the specific technical patterns and processes that make this collaboration effective in practice. One of the core technical challenges in collaborative development is maintaining context across sessions. This evolution represents more than just code refactoring - it's about creating explicit mechanisms for context preservation and retrieval. The AI can pick up exactly where it left off, even across different sessions or instances. We've developed a specific workflow for file collaboration that maintains consistency between human and AI contributions: 1. **Human commits changes to Git** - This establishes a clear baseline - All changes are versioned and traceable 2. **AI reads current file state** - Direct access to the latest committed version - No ambiguity about file contents 3. **AI proposes and writes changes** - Targeted updates to specific files - Maintains structure and style consistency 4. **Human reviews in their IDE** - Familiar environment for code review - Can make adjustments before committing This pattern ensures that both human and AI are always working from the same baseline, preventing confusion or conflicting changes. The core of our development workflow emerged naturally. For instance when we developed the basic Knowledge Sync Algorithm that we used to sync files and parse semantic content: ```python async def sync(self, directory: Path) -> None: """Sync knowledge files with the database.""" # Get current filesystem state vs DB state changes = await self.file_scanner.find_changes(directory) # Delete anything not in filesystem for path in changes.deleted: await self.delete_entity(path) # Process all files that need syncing parsed_entities = {} for path in [*changes.new, *changes.modified]: file_checksum = await self.file_scanner.calculate_checksum(directory / path) markdown_entity = await self.knowledge_parser.parse_file(directory / path) parsed_entities[path] = (markdown_entity, file_checksum) # Create/update entities (without relations) for path, (markdown_entity, checksum) in parsed_entities.items(): await self.sync_entity_without_relations(path, markdown_entity) # Process relations for path, (markdown_entity, checksum) in parsed_entities.items(): await self.sync_entity_relations(path, markdown_entity, checksum) ``` This algorithm emerged through collaborative iteration. Each decision point represents discussions about trade-offs, edge cases, and performance considerations. The key design decisions, such as "files as source of truth" and "outgoing relations only," came from this collaborative process - neither partner could have arrived at them independently as effectively. Through this work, we've discovered several key technical processes that enable effective collaboration: 1. **File-Based Communication** - Git as the shared record of truth - Clear ownership and history - Standard tools for both sides 2. **Context Preservation** - Explicit context loading and building - Session state preservation - Knowledge graph for semantic relationships 3. **Incremental Implementation** - Small, focused changes - Frequent testing and verification - Clear separation of concerns 4. **Explicit Decision Recording** - Design decisions captured in comments and commits - Reasoning documented alongside code - Future reference for both human and AI These patterns ensure that both parties always have access to the same information and context, minimizing misalignments and maximizing productive collaboration. We approach implementation in clear phases that play to the strengths of both partners: 1. **Human**: Strategic direction and problem definition 2. **AI**: Initial implementation proposal 3. **Human**: Review, testing, and feedback 4. **AI**: Refinement based on feedback 5. **Human**: Final approval and commit 6. **Both**: Documentation and knowledge capture This strategy maintains human oversight for critical decisions while leveraging the AI's ability to produce consistent, well-structured code quickly. Here's a simplified example of our collaborative cycle in practice: ```text # Session 1: Initial Implementation Human: We need a way to parse Markdown files into structured entities. AI: I suggest creating a MarkdownParser class with methods for extracting frontmatter, observations, and relations. Human: Makes sense. What about handling edge cases like malformed Markdown? AI: Good point. Let me revise with robust error handling... [Implementation discussion continues] # Session 2: Testing and Refinement Human: The parser works well on most files, but we're having an issue with Unicode characters. AI: [Reading the implementation from git] I see the problem. We're using the wrong encoding. Let me fix that... Human: Perfect. I'll commit this version. # Session 3: Extension AI: [Reading the latest implementation] Now that we have the basic parser working, should we implement the relation extraction functionality? Human: Yes, but let's make sure it aligns with our knowledge graph model... [Development continues] ``` Each session builds on the previous ones, with both participants maintaining a shared understanding of the code and its evolution. This collaborative model suggests several potential improvements to development tools: 1. **Better session persistence mechanisms** 2. **Integrated knowledge capture during development** 3. **File-focused collaboration interfaces** 4. **Explicit context management tools** 5. **Versioned development conversations** While we've built workarounds using existing tools, future development environments could be designed specifically for this kind of collaborative workflow. In the [final part](https://basicmemory.com/blog/ai-human-collaborative-development-3) of this series, we'll explore the human experience of this collaborative development model and its broader implications for the future of software development. --- Want to explore Basic Memory for yourself? Check out our [GitHub repository](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} to get started. # AI-Human Collaborative Development: The Human Experience (Part 3) In the [previous parts](https://basicmemory.com/blog/ai-human-collaborative-development-2) of this series, we explored the concept of AI-human collaborative development and the technical patterns that make it possible. Now, let's examine perhaps the most profound aspect: how this approach transforms the human experience of software development. There's a persistent myth in software development about "10x developers" who are dramatically more productive than their peers. The collaborative approach we've discovered suggests a different interpretation: it's not about having an AI that makes you 10x faster, but about transforming the development experience itself: - Never facing a blank editor alone - Always having a thought partner - Reducing decision fatigue - Maintaining momentum through challenges - Building shared knowledge over time The productivity gains come not from raw speed, but from removing the psychological barriers and cognitive load that typically slow development down. Traditional development often involves a lone developer staring at a problem, trying to figure out the right approach. Our collaborative model transforms this into a dialogue: ```text Me: I'm not sure how to approach this sync problem. We need to handle both file creation and deletion. Claude: Let's break this down. We have three cases: 1. Files in the filesystem but not in DB (new) 2. Files in both but with different content (modified) 3. Files in DB but not in filesystem (deleted) What if we start by scanning the filesystem and comparing against the database entries? Me: That makes sense. But how do we handle the case where a file was renamed? Claude: Good point. A rename would appear as a deletion plus creation. We could detect this by... [Exploration continues] ``` This ongoing dialogue makes complex problems more tractable by distributing the cognitive load and bringing multiple perspectives to bear. The impact on development timelines has been dramatic. Compare: - **Solo Development**: Basic Foundation took 6 months to create with traditional development methods - **Collaborative Development**: Basic Memory reached similar complexity in weeks rather than months This isn't just about speed - it's about the ability to tackle more ambitious projects with greater confidence and less fatigue. The collaborative approach transforms the culture of development in several key ways: Traditional development is often punctuated by frustrating roadblocks - bugs you can't solve, design decisions you can't make, or documentation you don't want to write. The collaborative approach turns these pain points into opportunities for dialogue: ```text Me: I can't figure out why this test is failing. The entity should be created but it's coming back null. Claude: Let's look at the test setup. I notice the async context isn't being properly initialized before the assertion. What if we add an await here? Me: That fixed it! Now let's document this pattern so we don't hit it again. ``` These moments of potential frustration transform into productive problem-solving sessions, helping maintain flow and momentum. Every developer has aspects of development they dislike - whether it's writing tests, creating documentation, or fixing edge cases. In the collaborative model, these burdens become shared: ```text Me: This feature is working, but I'm dreading writing all the error handling code. Claude: I can help with that. Let me draft comprehensive error handling based on our established patterns, and you can review and adjust. Me: Perfect. While you do that, I'll focus on the integration tests. ``` The ability to delegate parts of the development process (while maintaining oversight) reduces the psychological burden of less enjoyable tasks. Software development requires hundreds of small decisions, leading to decision fatigue over time. The collaborative approach turns decision-making from a burden into a dialogue: ```text Me: I'm not sure whether to implement this as a class or a set of functions. Claude: Let's consider the tradeoffs. A class would give us state encapsulation, but functions might be more testable. Given our current architecture pattern of... [Discussion of tradeoffs] Me: Based on that analysis, I think functions make more sense here. ``` Instead of carrying the full weight of each decision, the process becomes one of weighing options together, leading to better outcomes with less cognitive strain. Through this process, we've learned several key things about how collaborative development affects the human experience: First, the nature of problem-solving changes fundamentally: - Distributed thinking reduces cognitive load - Continuous dialogue maintains momentum - Collaborative debugging reduces frustration - Shared responsibility for documentation improves willingness The scope of what feels achievable also expands: - Projects previously considered too complex become approachable - Confidence to tackle ambitious challenges increases - Broader exploration of solution spaces occurs naturally - Willingness to consider alternatives grows Perhaps most importantly, the emotional experience of development transforms: - No more solo debugging sessions - Shared problem-solving reduces psychological burden - Continuous progress maintains motivation - Complex learning curves become collaborative adventures And knowledge accumulation accelerates: - Git commits capture decision points - Conversations document rationale - Code reviews become learning opportunities - Shared context builds over time This model of human-AI collaboration makes a lot of things possible: More ambitious projects become accessible. As a developer, I can tackle complexity that would otherwise be overwhelming. Long-term projects become more sustainable, and experimental approaches carry less risk. Learning curves become less daunting. New technologies can be explored collaboratively, knowledge gaps are filled through dialogue, and documentation becomes continuous and contextual. Development becomes more enjoyable, with reduced isolation and frustration, more balanced cognitive load, and continuous forward progress. Complex systems can be built more reliably, with multiple perspectives catching edge cases, consistent patterns emerging naturally, and improved documentation and testing. The real breakthrough in AI-human collaborative development isn't just the technical achievements, but discovering how to make complex development sustainable and enjoyable through true collaboration. This isn't about AI replacing developers or simply acting as a productivity tool. It's about creating a fundamentally new development experience where the strengths of both human and artificial intelligence combine to create something greater than either could achieve alone. The most impactful thing isn't AI that writes code for us, but AI that thinks with us - transforming development from a solitary struggle into something that actually feels collaborative. --- Want to explore Basic Memory for yourself? Check out our [GitHub repository](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} to get started. # We Read the AI Memory Research So You Don't Have To *Dozens of papers. One question: how should AI actually remember things?* AI memory is really having its moment. In the last three months, researchers have published dozens of papers on how to make AI agents remember things across conversations. [One survey alone](https://arxiv.org/abs/2512.13564){rel=""nofollow""} had 47 authors. The field is moving so fast that papers are citing other papers from the same month. We read them. Most of them, anyway. A few things stood out from the bunch. ## Your brain doesn't use one filing cabinet The paper that stuck with us most is called ["The AI Hippocampus."](https://arxiv.org/abs/2601.09113){rel=""nofollow""} A team of researchers mapped AI memory systems against the human brain and found something that keeps showing up across the literature: systems that separate memory into distinct types consistently outperform systems that throw everything into one pile. Your brain does this naturally. You have: **Episodic memory.** Yesterday's meeting. The moment you realized the database schema was wrong. Events, in order, with context. **Semantic memory.** What you know. You don't remember every conversation about JavaScript, but you know JavaScript. This is distilled knowledge, stripped of the specific moments that created it. **Procedural memory.** How you do things. Typing. Debugging. The muscle memory of your craft. **Working memory.** What you're thinking about right now. The problem in front of you. Temporary, focused, gone when you move on. The researchers found that AI systems mimicking this separation perform better at recall, reasoning, and long-term coherence. The ones that dump conversations, facts, and instructions into the same bucket get confused. Makes sense. You wouldn't store a recipe and a diary entry in the same place and expect to find either one quickly. ## Sleeping on it actually works Multiple papers converged on the same finding: memory consolidation is a big deal. A paper called [MemFly](https://arxiv.org/abs/2602.07885){rel=""nofollow""} (even research is starting to sound like an AI project these days) used so-called information bottleneck theory (a formal way of measuring compression vs. usefulness) to show that layered memory, where raw information gets reviewed, compressed, and promoted to long-term storage, outperforms flat memory on every metric they tested. Another paper, [TraceMem](https://arxiv.org/abs/2602.09712){rel=""nofollow""} (again with the names) found that when you extract narrative arcs from conversations instead of just pulling out isolated facts, recall improves significantly. Your brain does this too. You don't remember a meeting as a list of bullet points. You remember a story: we started here, realized this, decided that. The implication is clear. AI memory systems that periodically review raw memories and consolidate them into refined knowledge do better than systems that just accumulate forever. Your brain does this while you sleep. The research suggests AI should do it too. ## The forgetting problem Here's a finding lots of people are butting against: AI memory systems are terrible at forgetting. They just accumulate. Every fact, every conversation snippet, every piece of context piles up. Your AI memory is like its own plastic island, drifting around, never biodegrading. Old information sits next to new information with no way to tell which is current. A paper on self-organizing memory systems ([EverMemOS](https://arxiv.org/abs/2601.02163){rel=""nofollow""}) found that conflicting memories, where old facts directly contradict newer ones, degrade performance significantly. And most systems have no mechanism to detect or resolve this. Your brain handles this with elegant brutality. Memories decay unless reinforced. The stuff you revisit gets stronger. The stuff you don't fades. Current AI memory systems don't do this. The [47-author survey](https://arxiv.org/abs/2512.13564){rel=""nofollow""} identified forgetting as one of the six core memory operations, and the one that most systems handle worst or not at all. ## What we took away from all of this Three things: **Separation matters.** Daily logs, curated knowledge, workflow instructions, and active conversation should live in different places, organized differently, accessed differently. Mixing them is a design mistake the research keeps validating. Basic Memory handles this through projects, note types, and tags — keeping different kinds of knowledge organized so your AI can find the right thing at the right time. **Review and consolidation are not optional.** Raw memory accumulation is a dead end. Systems need a process for distilling what matters, connecting ideas, and letting the rest go. The papers call this "sleep-time compute." We call it the `memory-reflect` skill. The `memory-lifecycle` and `memory-defrag` skills handle the rest — archiving what's no longer active and keeping your knowledge base clean as it grows. **Transparency solves problems that algorithms can't.** The forgetting problem and the contradiction problem are genuinely hard to solve in code. But they get a lot easier when you can see the memory. You can spot the outdated note. You can notice that two things contradict each other. You can fix it. Basic Memory stores everything as plain text files you can open, read, and edit anytime. Systems that hide their memory from the user can't offer this, no matter how sophisticated the algorithm. We're a small team. We read these papers because this is what we build. Every finding either validates a decision we already made or points us in the direction of what to build next. --- *Basic Memory gives your AI memory it can read, edit, and keep. [Try it free →](https://app.basicmemory.com/auth/signup){rel=""nofollow""}* # Basic Memory Cloud Beta Is Live! Big milestone today: **Basic Memory Cloud is officially live in open beta.** If you’ve been following along with our local-first release, this update brings everything great about Basic Memory--Markdown-based, user-owned and controlled—into a new cloud environment designed to make your memory available everywhere you work. ## What’s New - **Multi-LLM support**: Basic Memory Cloud now works with all LLMs that support remote MCP, including Claude, ChatGPT, and Gemini CLI. Start a research thread in Claude on your laptop, continue it in ChatGPT on your phone, and reference it later in Gemini—without losing any context. It's also designed to work in Claude Code and Codex, letting you bring your memory to whatever environment you prefer. - **Cross-device support**: desktop, web, tablet, and phone. Whether you’re chatting on your laptop or referencing notes on your phone, your memory is always within reach. - **A note-taking web app**: your memories now live in one simple, accessible interface. The new web app gives you a dedicated place to browse, edit, and manage everything you and your AIs have built together. ## The Big Idea Basic Memory started as an experiment in local-first AI memory, a way to retain your context in plain Markdown so your knowledge lives in a format both you and AI can understand. That principle hasn’t changed. Cloud just extends the idea: your same files, still yours, but now accessible across devices and interfaces: portable, accessible, and ready wherever and whenever you are. If you're the kind of person who keeps long-running projects, prompts, or research threads alive across multiple AIs, this release will be a huge leap forward. Even if you only use one AI, your knowledge should belong to you and you alone. That's what we're building toward. ## Pricing During beta, lock in Basic Memory Cloud at $14.25/month forever (25% off the $19 launch price). Includes a 7-day trial. [Join the beta](https://basicmemory.com/beta){rel=""nofollow""} ## A Note to our Community Our open-source version isn’t going anywhere. The local-first version remains fully supported and free for everyone who prefers to self-host or keep their notes local. Cloud is an additional layer, one we built because so many of you asked for a way to use Basic Memory across devices and models without giving up ownership or transparency. To everyone who participated in customer interviews, tested, filed issues, broke things, and kept sending thoughtful feedback: thank you. We can’t wait to hear what you think of Cloud, and how you’ll use it in your workflows. Please feel free to share your impressions, bugs, and wish-lists in our [Discord](https://discord.gg/tyvKNccgqN){rel=""nofollow""}. It's still the easiest place to find us. The Basic Memory Team # Basic Memory Cloud February 2026: A Real Editor, Finally I've been waiting to write this post for a while. When we launched Basic Memory Cloud, the editing experience was... fine. It worked. You could write notes, link them together, and let AI help you build your knowledge graph. But if I'm being honest, every time I needed to do serious editing, I found myself wishing I was in my local setup instead. That changes today. The February 2026 release brings a proper editor to Basic Memory Cloud—one that actually feels good to use. ## The New ProseKit Live Editor We rebuilt the editor from scratch using ProseKit, which shares architectural DNA with ProseMirror. The result is three distinct modes that let you work the way you want: ![Editor modes - Live, Preview, and Source](https://basicmemory.com/images/blog/editor-modes.gif) **Live Mode** gives you true WYSIWYG editing. When you bold something, it's bold. No markdown syntax cluttering your view, no mental translation required. For people who came to Basic Memory from tools like Notion, this is probably what you expected all along. **Preview Mode** strips away the editing chrome and gives you a clean reading view. More importantly, your wikilinks become clickable—you can navigate your knowledge graph without switching contexts. I've been using this constantly when reviewing notes before AI sessions. **Source Mode** is for those of us who think in markdown. Raw text, full control, no surprises. If you're coming from Obsidian or Foam, you'll feel right at home. The toolbar handles the basics—bold, italic, strikethrough, inline code, links—but the real magic is the slash menu. Type `/` and you get quick access to headings, lists, code blocks, whatever you need. No mouse required. ![Live editor with slash menu](https://basicmemory.com/images/blog/editor-live-mode.png) ## Wikilink Autocomplete Actually Works This one matters. When you type `[[`, the editor now suggests matching notes from your knowledge base. Start typing a title, and it narrows down the options. Hit enter, and the link is inserted. It sounds simple, and it should be. But getting autocomplete to feel snappy when you've got thousands of notes? That took some work. We're pulling suggestions in real-time, ranked by relevance, and the whole interaction stays under 100ms even on larger knowledge bases. For anyone building interconnected notes—which, if you're using Basic Memory, is probably everyone—this removes a ton of friction. No more switching tabs to check exact note titles. No more broken links because you misremembered a name. ## Command Palette (Cmd+K) Every modern app has one now, and for good reason. Hit Cmd+K and you can: - Jump to All Notes, Recent, or Pinned - Trigger a sync - Open Settings or Snapshots - Execute pretty much any action without touching the mouse ![Command palette](https://basicmemory.com/images/blog/command-palette.png) We kept the implementation simple. No fancy fuzzy matching algorithms, just straightforward prefix search that gets you where you need to go. If you've used VS Code or Linear, you know the pattern. ## Keyboard Shortcuts for Everything I'm a keyboard person. Reaching for the mouse breaks my flow. So we added shortcuts for... basically everything: - **Cmd+B** / **Cmd+I** / **Cmd+E** for bold, italic, and inline code - **Cmd+Alt+1/2/3** for heading levels - **Option+Shift+Up/Down** to move lines around - **Cmd+Shift+M** to cycle through editor modes - **Cmd+/** to see all available shortcuts (because who remembers all of these?) ![Keyboard shortcuts reference](https://basicmemory.com/images/blog/editor-shortcuts.png) The line movement shortcuts are surprisingly useful. When you're reorganizing observations or reordering a list, being able to shuffle lines without cut-paste makes a real difference. ## Better Browsing The Observations & Relations browser now has proper filter tabs. You can view everything, or narrow down to just Notes, Observations, or Relations. Category badges give you visual context at a glance—you can immediately tell whether you're looking at a fact, a decision, or a technique. This ties directly into how Basic Memory structures knowledge. Your notes contain observations (things you know) and relations (how things connect). The browser now makes that structure visible and navigable. ## The Small Stuff That Adds Up **Pinned notes sync across devices now.** Previously they were local-only, which was annoying if you work on multiple machines. Fixed. **You can move and delete folders.** File management in the browser used to be limited to notes. Now you can reorganize your whole structure without dropping to the filesystem. **The frontmatter panel is actually useful.** Edit your note's title, type, permalink, and tags without touching the source. This matters more than you'd think when you're cleaning up auto-generated notes from AI sessions. ## Why We Built This Here's the thing: Basic Memory exists because we believe your knowledge should live in plain text files that you control. That philosophy doesn't change just because you're using our cloud service. But "plain text you control" doesn't have to mean "mediocre editing experience." The local Basic Memory experience—using your own editor, your own filesystem, your own backup strategy—is still first-class. Some people will always prefer that, and we're fine with it. But for people who want the convenience of cloud sync, AI integration, and access from anywhere, the editing experience should be just as good. With this release, I think we're there. I've been using the new editor for the past few weeks, and I don't find myself reaching for my local setup anymore. That's the bar we were aiming for. ## What's Next We're not done. The editor will keep improving—better table support, more keyboard shortcuts, maybe even some vim bindings for the truly devoted. The browser needs work too; search could be faster, and we want to add more visualization options for exploring your knowledge graph. But for now, go try it. If you're already on Basic Memory Cloud, the new editor is live. If you're not, there's never been a better time to start. Try Basic Memory free at [basicmemory.com](https://app.basicmemory.com/auth/signup){rel=""nofollow""} --- **Further Reading:** - [GitHub - basicmachines-co/basic-memory: AI conversations that actually remember](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} - [Basic Memory Documentation](https://docs.basicmemory.com){rel=""nofollow""} - [Basic Memory Cloud - Try it free](https://app.basicmemory.com/auth/signup){rel=""nofollow""} # OpenClaw Built Its Own Basic Memory Plugin We've released [openclaw-basic-memory](https://github.com/basicmachines-co/openclaw-basic-memory){rel=""nofollow""}, a Basic Memory plugin for OpenClaw that gives your agent persistent, searchable memory across sessions. And the best part is how it got made. We installed [OpenClaw](https://www.digitalocean.com/resources/articles/what-is-openclaw){rel=""nofollow""}, pointed it at the Basic Memory codebase, and told it to build a plugin. It read through the source, figured out the architecture, wrote a working integration, ran the tests, iterated on what broke, and submitted pull requests back to the repo. All by itself. The plugin it wrote solves a real problem. If you've used OpenClaw for any serious work, you've hit the moment where your agent just forgets everything. The community calls it the "lobotomy problem," and one user [documented losing roughly 45 hours](https://github.com/OpenClaw/OpenClaw/issues/5429){rel=""nofollow""} of accumulated work to context compaction. OpenClaw's memory relies on local files loaded at startup, and when conversations get long enough, compaction clears the history to stay within token limits. For quick tasks this barely matters. For sustained work where your agent has built up real context over hours, it's painful. Bigger context windows don't fix it. Studies show that dumping an entire conversation history into a large window actually degrades reasoning quality. Memory is a knowledge management problem, not a context window problem. So why could OpenClaw build this plugin on its own? Because Basic Memory's codebase is structured as a navigable knowledge graph. OpenClaw didn't need us to explain how anything worked. It explored the code, pulled connected concepts, understood how the pieces fit together, and wrote something functional. We reviewed it, made some tweaks, and shipped it. ## How the Plugin Works ::div --- style: "background: #0f172a; border-radius: 8px; padding: 24px; text-align: center;" --- ![How Basic Memory works with OpenClaw](https://basicmemory.com/images/blog/openclaw-basic-memory-architecture.png){style="max-width: 500px; width: 100%; display: inline-block;"} :: [openclaw-basic-memory](https://github.com/basicmachines-co/openclaw-basic-memory){rel=""nofollow""} gives OpenClaw agents persistent memory backed by a semantic knowledge graph. When your agent has a conversation, the plugin captures it as structured Markdown notes with observations, categories, and relations. Each note links to others through shared topics and `memory://` URLs, building a knowledge graph that grows over time. When your agent needs context from a previous session, it searches the graph and pulls back connected concepts rather than scanning flat text. The plugin gives your agent seven tools for working with the knowledge graph. `bm_search` and `bm_context` handle semantic search and graph navigation, letting the agent find relevant notes and explore connected concepts at different depths. `bm_read`, `bm_write`, and `bm_edit` cover the basics of reading, creating, and modifying notes. `bm_delete` and `bm_move` round things out for cleanup and organization. There are also two slash commands for quick access: `/remember ` saves a brief note, and `/recall ` searches the knowledge graph right from the chat. ## Three Ways to Use It We designed three modes so you can adopt it however makes sense. **Archive Mode** is the gentlest start. It runs alongside OpenClaw's existing memory system and quietly captures your conversations as structured notes in the background. Your current workflow doesn't change at all. You just start accumulating a searchable knowledge graph over time. Set `autoCapture: true` and forget about it. **Agent-Memory Mode** replaces OpenClaw's built-in memory entirely. Your agent reads and writes to the knowledge graph for all its context, using semantic search and graph navigation instead of flat file loading. This gives you the fullest experience but changes how memory works at a fundamental level. **Both Mode** runs them together. You get the archive capturing everything in the background plus the full knowledge graph tools for retrieval. Maximum coverage if you want everything. In all three modes, your data lives as plain Markdown files on your filesystem, by default in `~/.basic-memory/openclaw/`. You can open them in any text editor, commit them to git, or browse them in Obsidian. OpenClaw takes a CLI-first approach and [doesn't use MCP](https://github.com/openclaw/openclaw/issues/4834){rel=""nofollow""}, so the plugin talks to Basic Memory through its CLI (`bm tool search-notes`, `bm tool read-note`, etc.) rather than the MCP server. Same knowledge graph, same data. And since those same notes are accessible via MCP, any tool that does support the protocol can read them too. ## Setup Install the Basic Memory CLI: ```bash uv pip install basic-memory ``` Clone and install the plugin: ```bash git clone https://github.com/basicmachines-co/openclaw-basic-memory cd openclaw-basic-memory bun install ``` Add it to your OpenClaw config: ```json5 { plugins: { entries: { "basic-memory": { enabled: true, config: { mode: "archive", project: "my-project", autoCapture: true } } } } } ``` That's it. Start a conversation and your agent will begin building its knowledge graph. In Archive Mode the plugin runs silently in the background. If you switch to Agent-Memory Mode, your agent will start using `/remember` and `bm_write` on its own to save important context. You can also access notes directly from the command line: ```bash openclaw basic-memory search "authentication decisions" openclaw basic-memory read "Project Architecture" openclaw basic-memory context "memory://project/design-decisions" --depth 2 openclaw basic-memory recent --timeframe 7d openclaw basic-memory status ``` ## Memory Across the Agent Ecosystem The agent landscape is fragmenting fast. OpenClaw, Claude Code, Cursor, Windsurf, Copilot, and more are all shipping their own approaches to memory, and none of them talk to each other. Your context with one agent stays locked inside that agent. Switch tools and you start over. Basic Memory sits underneath all of them. Agents that support MCP connect directly. For ones that don't, like OpenClaw, Basic Memory's CLI works just as well. The decisions you captured working with Claude Desktop are there when you open OpenClaw. The architecture notes your coding agent wrote are searchable from VS Code. One knowledge base, many agents, and it's all just Markdown files on your filesystem that you actually own. We think that's where this is headed. Agents will keep getting better, new ones will keep appearing, and the one thing you shouldn't have to rebuild every time you try a new tool is your accumulated knowledge. Basic Memory bridges the gap between human memory and machine memory by keeping everything in a format both can work with. Your agent writes structured notes, you read and edit them in plain Markdown, and the knowledge compounds for everyone. The plugin is fully open source. Check out the [GitHub repo](https://github.com/basicmachines-co/openclaw-basic-memory){rel=""nofollow""}, or try Basic Memory free at [basicmemory.com](https://app.basicmemory.com/auth/signup){rel=""nofollow""}. # Announcing Basic Memory Teams ## Basic Memory Teams is here. And boy are our fingers tired. With this launch, you can share a common knowledge base with your colleagues, friends, agents, and collaborators without spending a penny more. From the beginning, we've dreamed of a Basic Memory that is fully collaborative, not just between you and your AI, but with anyone you want to be able to contribute, read, or edit the context you're sharing together. As the release date has drawn near, we've talked a lot about where Teams fits into our product lineup. Who is our ICP? Is it its own product, an add-on, a B2B exclusive? Finally, we decided that it's none of those things. **It's for everyone!** So every Basic Memory Cloud user can invite any other member to share a knowledge base—or "memory layer" or "memory bank" or "truth layer." If you've been using the V2 web app, you've already seen the new way your notes are organized. Your projects, folders, and notes are now navigable via the left menu bar. Now, along with your personal projects, you can create fully independent Teams projects and folders with anyone you choose. ![The Basic Memory V2 app showing personal and team knowledge bases side by side](https://basicmemory.com/images/blog/basic-memory-teams-v2-app.png) We've been dogfooding it for weeks, and it's been truly incredible. One thing we've learned over the past year and a half is that a lot of the time we're all looking for a piece of information another of our teammates has. > Hey, did Drew finish that Teams post? I want to pull a quote for the newsletter. > I think so? He sent me a draft on Tuesday but I have no idea if it's the latest. > Isn't he at that silent retreat in Thailand? > Until next Wednesday. It's exactly the kind of thing that stops all progress in its tracks and gives everyone another excuse to just open a YouTube tab or reach for their phone. Thanks to Teams, it doesn't have to. Our users have given us lots of insight into the ways they would use a shared workspace. From the Dungeon Master who wanted to share character sheets with his players to the person who uses Basic Memory with her staff to coordinate sales calls, from first contact to closing deals. Or, more excitingly to many of our users, as a "shared memory substrate" for a swarm of agents. Until now, that kind of collaboration required some pretty creative workarounds. Now, it's as easy as clicking on your shared projects or asking your AI to read or add to them. ## What you can actually do A few things worth knowing about how it works. **Edit notes together in real time.** Two of you in the same doc, typing at the same time, with avatars in the header showing who's where. No more emailing drafts back and forth or pinging each other to ask who's got the latest version. Underneath, the file is still plain Markdown sitting in your knowledge graph, exactly like the rest of Basic Memory. **You decide who sees what.** Head to Settings → Teams and you can invite people as Admins, Editors, or Viewers. Some projects you'll want open to the whole team—the shared research, the running list of customer interviews, the company handbook. Others you'll want tighter—hiring conversations, contracts, half-baked ideas you're not ready to show off yet. You set it per project. **Every save is a version.** If a teammate accidentally pastes over your morning's work, or your AI gets a little too enthusiastic with an edit, file history has your back. Open it up, find the version you want, pull back what you need. Nothing is ever actually gone. **An Activity feed that catches you up fast.** The Activity menu shows everything happening across your workspace—who edited what, when, including your AI agents. Step away for a long lunch and catch up in thirty seconds when you get back. ## The part we're most excited about Here's the thing that makes Teams different from any other shared workspace: when your team shares a knowledge graph, your AI assistants share it too. Ask Claude about last quarter's pricing discussion and it can pull from the actual meeting notes your colleague took, the follow-up doc your PM wrote, the decision your founder made in a Slack thread someone bothered to save. It's not just your knowledge. It's everything the team knows. ## Try it If you're already a Basic Memory Cloud user, watch for the popup in your left sidebar—one click switches you on. If you're not, [start here](https://app.basicmemory.com/auth/signup){rel=""nofollow""}. The team docs walk through invitations, roles, and what the first day looks like for someone you've just added. Now go invite someone. # Basic Memory v0.19.0: Search That Understands What You Mean We just shipped **v0.19.0** — the biggest release since we launched. Sixty-six commits, three months of work, and a fundamental change in how your AI finds what it knows. Every AI tool is building memory right now. Claude has CLAUDE.md and auto memory. ChatGPT remembers facts about you. Cursor stores preferences. These are useful — but they're short-form, siloed to one tool, and you can't search them. This release is what makes Basic Memory the knowledge layer that sits above all of them: semantic search that finds meaning, schemas that keep your knowledge consistent, and cloud routing that makes it available everywhere. Here's what matters. ## Semantic Search, Everywhere Until now, Basic Memory searched your notes the way `grep` does: match the words, return the results. It works. It's fast. And it completely fails when you search for "login security improvements" but your notes say "authentication hardening." **v0.19.0** adds semantic search — hybrid by default, combining keyword matching with meaning-based retrieval. It ships enabled out of the box. No configuration. No separate embedding service. No API keys. Install, and it works. ```text "How do I speed up the app?" ``` That question now finds your note about "performance optimization strategies" even though you never used the word "speed." The embedding model runs locally, your data never leaves your machine, and the results are ranked by a fusion of exact matches and semantic similarity. You don't have to think about search modes. Basic Memory describes them to your AI, and your AI picks the right one based on what you ask. But if you want control, there are three: - **hybrid** (default) — best of both worlds - **text** — keyword-only, like before - **vector** — pure semantic similarity For most people: just search normally. It got smarter. ## Schemas: Your AI Checks Its Own Work Knowledge bases grow organically. You write thirty person notes and realize half say `[name]`, a quarter say `[full_name]`, and a few just put the name in the title. Relation types drift — `works_at`, `employed_by`, `employer` — all meaning the same thing. The new schema system lets you define what "consistent" means, then validate against it. The key design decision: **schemas are just notes** in your knowledge base. ```text "Look at my meeting notes and figure out what structure they have in common. Then create a schema so new meetings are consistent." ``` Your AI analyzes existing notes, identifies patterns, proposes a schema, and you approve it. Then it checks the outliers and offers to fix them. No migration scripts. No database alterations. Just a conversation about what "good" looks like for your notes. The schema itself is a regular markdown file you can edit in any text editor: ```yaml --- title: Meeting type: schema entity: meeting schema: attendees: string[], who was there date: string, when it happened decisions?: string[], what was decided action_items?: string[], what needs to happen next --- ``` We built `schema_infer`, `schema_validate`, and `schema_diff` as tools — so your AI can infer schemas from what exists, validate notes against a definition, and detect drift over time. ## Per-Project Cloud Routing This one's for people running both local and cloud projects. You can now choose where each project lives — on your machine or in Basic Memory Cloud — and mix freely. ```bash bm project set-cloud research # this project syncs to cloud bm project set-local private-notes # this one stays on your machine ``` Your AI uses the same tools regardless of where the data lives. You decide what's sensitive and what's portable. Keep personal notes local, route work projects to the cloud so they're available from any device. Three levels of control: global default, per-project override, per-command flag. Mix and match however makes sense for your setup. ## Agent Skills We added a set of reusable skills that teach your AI best practices for working with Basic Memory. Instead of explaining how to write good notes every conversation, you install a skill once and your AI follows it automatically. - **memory-notes** — How to structure notes with observations, relations, and tags - **memory-schema** — When and how to create and use schemas - **memory-reflect** — Periodic review and connection-building across your knowledge base Skills work in Claude Code, Claude Desktop, and any tool that supports the MCP skills pattern. They're markdown files — readable, editable, and shareable. [See the full list →](https://docs.basicmemory.com/integrations/skills){rel=""nofollow""} ## The Small Things That Matter **Write protection.** `write_note` no longer silently overwrites existing notes. If a note exists, you get an error instead of data loss. Use `edit_note` for updates instead. This one change will save someone's knowledge base — AI assistants are enthusiastic writers. **Smarter note editing.** `edit_note` gains two new operations: `insert_before_section` and `insert_after_section`. Your AI can now add content relative to a section heading without replacing what's already there — useful for building up notes incrementally while preserving existing work. **Metadata search.** Filter notes by any frontmatter field — status, priority, tags, custom fields. Ask your AI something like: ```text "Show me all my decisions tagged as security-related" "Find notes with status in-progress and high priority" ``` Your AI translates these into structured metadata queries automatically. No need to know the filter syntax. **Project dashboard.** `bm project info` now shows a dashboard with bar charts for note types, embedding coverage, and health status. It's the fastest way to see what's in your knowledge base. **JSON output.** Every tool supports JSON output for scripting and automation. If you're building on top of Basic Memory, this makes your life easier. ## The Upgrade ```bash # uv uv tool upgrade basic-memory # Homebrew brew upgrade basic-memory ``` After restarting, Basic Memory will rebuild your search index with embeddings. ```bash ❯ bm project info main Basic Memory initialized ✓ ╭─────────────────────────────────────── main ────────────────────────────────────────╮ │ Knowledge Graph Embeddings │ │ Entities 476 ● Semantic Search Enabled │ │ Observations 1306 Provider fastembed │ │ Relations 682 Model bge-small-en-v1.5 │ │ Unresolved 383 Indexed ████████████████████ 476/476 │ │ Isolated 248 Chunks 17906 │ │ ● Status Up to date │ │ │ │ Note Types │ │ note ████████████████████████████████████████ 390 │ │ file ███░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 28 │ │ experiment █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 11 │ │ specification █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 8 │ │ knowledge █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 5 │ │ +19 more types │ │ │ │ ~/basic-memory default: main 2026-03-07 14:12 │ ╰──────────────────────────────── Basic Memory ──────────────────────────────────────╯ ``` To create them manually, run: ```bash bm reindex --embeddings ``` The reindex generates vector embeddings for semantic search — a one-time operation that takes a few minutes depending on the size of your knowledge base. Cloud projects handle this automatically. Everything else is backward compatible. Existing notes, permalinks, and workflows keep working. New defaults are saner, and the old behavior is one config flag away if you need it. [Full release notes →](https://docs.basicmemory.com/whats-new/v0.19.0){rel=""nofollow""} --- ## Try It Basic Memory is open source and free to run locally. If you're already using it, `uv tool upgrade basic-memory` gets you everything above. **New to Basic Memory?** The fastest way to start is [Basic Memory Cloud](https://app.basicmemory.com/auth/signup){rel=""nofollow""}. Sign up, connect your AI tool, and you're working with a persistent knowledge base in under two minutes — no install, no configuration. Cloud gives you everything in the open-source release plus: - **Access from any device** — your knowledge base works from your desktop, laptop, phone, or any AI tool - **Works with every major AI** — Claude Desktop, ChatGPT, Gemini, Claude Code, Cursor, Codex — connect once and your notes are available everywhere - **Web editor** — browse, search, and edit notes directly in your browser - **Automatic backups** — daily snapshots so your knowledge is always safe - **Local sync** — sync notes to your machine for offline access and Obsidian integration If you prefer to run everything locally, the [local quickstart](https://docs.basicmemory.com/start-here/quickstart-local){rel=""nofollow""} takes about five minutes. # Basic Memory v0.13.0: 13 is a Lucky Number *June 11, 2025* We're excited to share Basic Memory v0.13.0 - our biggest release yet! This one's been brewing for months, and it fundamentally changes how you organize and work with your knowledge using an LLM. ## The Big Idea: AI-Managed Project Switching Basic Memory has had multiple projects for a while, but there was this annoying dance: switch projects via CLI, restart Claude and the MCP server, then continue your conversation in the new context. It worked, but it was clunky. v0.13.0 changes everything. Now Claude itself can manage your projects during a conversation. No restarts, no command-line juggling - just natural project switching that happens in real-time. ```text 💬 "Switch to my work project" 🤖 ✓ Switched to work-notes project • 47 entities • 125 observations • 23 relations 💬 "What did I work on yesterday?" 🤖 [Shows only work-related recent activity] ``` ![Switch Projects](https://basicmemory.com/images/basic-memory/claude-switch-project.png) The magic is that everything just *works*. Search, recent activity, note creation - it all happens within your current project context. No more accidentally mixing personal thoughts with work notes. **Power user tip**: Most tools also support cross-project operations when you need them. You can do `edit_note("Meeting Notes", project="work-project")` to edit a note in a different project without switching contexts. There are also `list_projects` and `list_directory` commands so Claude can see all your knowledge across projects when needed. ## Edit Notes Without The Friction Here's a feature I've heard asked a for a lot: to update a note, the AI had to read the whole thing, copy it, edit it, and write it back. Like using a typewriter in the age of word processors. v0.13.0 adds **incremental editing** - you can now append, prepend, find/replace, or update specific sections: ```python # Add a quick update to meeting notes edit_note("team-standup", "append", "## Follow-up: John will handle the deployment") # Update that outdated config info edit_note("api-docs", "find_replace", "v0.12.0", find_text="v0.11.0") # Prepend today's date to your journal edit_note("daily-journal", "prepend", "## June 5, 2025\nStarting the day with...") ``` ![Edit Note](https://basicmemory.com/images/basic-memory/claude-edit-note.png) No more rewriting entire documents. Just quick, surgical updates that feel natural. ## Move and Organize Like You Think File organization used to be this whole production - manually moving files, sync changes back to the database, hoping nothing broke. Now it's just: ```python move_note("old-idea", "projects/active/big-idea.md") ``` Basic Memory handles everything: creates folders if needed, updates the database, preserves all your links and relationships. It's how file management should work. ## The View Tool That Changes Everything This one's our favorite new feature - and it was actually a last-minute addition! In Claude Desktop, you can now use `view_note` to display notes as beautiful, formatted **artifacts** instead of raw markdown. Instead of squinting at: ```text --- title: Meeting Notes --- # Meeting Notes - [action] Fix the bug\n ``` You get a clean, readable artifact that looks like an actual document. It's particularly amazing for long notes or complex content with lots of formatting. ![View Note](https://basicmemory.com/images/basic-memory/claude-view-note.png) ## Projects in Practice Let me show you how this actually works in daily life. Suppose I have these projects: - **work**: All client stuff, meeting notes, project docs - **coffee**: Curiously detailed notes about coffee preparation - **personal**: Journal, ideas, random thoughts - **basic-memory**: Development notes, feature ideas, user feedback Mid-conversation with Claude, I can say "switch to my learning project" and suddenly we're only working with my study materials. No mental overhead, no accidental context mixing. The really cool part? Each project maintains its own knowledge graph. Relations and connections stay within their domain, making searches more relevant and contexts cleaner. ![List Projects](https://basicmemory.com/images/basic-memory/claude-list-projects.png) ## Technical Stuff (For the Curious) Under the hood, we moved from per-project SQLite databases to a single database index. Sounds boring, but it enables the seamless project switching and much better performance. The real challenge was maintaining 100% test coverage while adding all these features. We already had 100% coverage, and keeping it there while implementing multi-project management, incremental editing, and file operations was... intense. The features themselves were done a while ago, but we spent weeks making sure every edge case was covered. We also built a whole second integration test suite that uses the MCP client to invoke a standalone MCP server - testing the actual tools as they'd be used in real life, not just unit tests. The coolest part? We created test suite in Claude Code, `.claude/commands/test-live.md` where Claude itself runs comprehensive tests, exercising all the tools for over 30 minutes and recording results directly in Basic Memory. Claude testing Claude tools using Claude's own knowledge management system. Meta doesn't begin to cover it. ## Try It Out Complete installation instructions are in our [Getting Started docs](https://docs.basicmemory.com/getting-started#configure-claude-desktop){rel=""nofollow""}. **Upgrade** ```bash # Upgrade and existing install uv tool upgrade basic-memory ``` **First-time upgrade note**: When you install v0.13.0, Basic Memory will re-index all your projects into the new unified database. Your filesystem is always the source of truth, so there's no risk of data loss, but this can take a few minutes depending on how much content you have. You can check progress with the new `sync_status` tool. If you're new to Basic Memory, check out our [getting started guide](https://docs.basicmemory.com/getting-started){rel=""nofollow""}. ## What's Next This release sets us up for some genuinely exciting possibilities. Multi-project support was the foundation we needed for what's coming: ### Basic Memory Cloud We already have an OAuth proof-of-concept working, and we're building **Basic Memory Cloud** - a SaaS version that brings all these project management and editing capabilities to the web. Think of it as your knowledge graph, accessible anywhere, with the same MCP tools Claude loves, but now through a browser with a Notion like web editor. I'm really excited about this. ### Agentic Task Execution Here's where it gets really interesting: we're implementing a system similar to Claude Code's prompt commands, but for Basic Memory. Imagine creating a note, then calling `basic-memory command ` to have Claude execute complex tasks driven by your prompt instructions. ```markdown --- title: World Domaination plan type: prompt permalink: world-domination --- # World Domaination plan - [action] ... ``` Claudeception level: infinite. 🤯 ### Business Memory for Enterprise We're also working on using Basic Memory as the "Business Memory" for agentic workflows with MCPs. Picture this: read all your CRM data, automatically generate structured notes, then get rich, contextual insights from an LLM that actually remembers everything about your business relationships and history. The v0.13.0 architecture makes all of this possible. Each of these directions builds on the project isolation, incremental editing, and robust tool ecosystem we've just shipped. But first, we're curious to hear how you use projects in practice. Do you organize by domain? By time? By workflow? Each person's approach teaches us something new about how knowledge actually wants to be structured. Happy note-taking! *Paul* --- *Basic Memory is local-first knowledge management that combines note-taking with knowledge graphs. It keeps your data under your control while making it incredibly easy to find connections and build understanding over time.* # Basic Memory vs Mem0 vs Letta vs Everyone Else The AI memory space has gotten crowded fast. In the last year: Mem0 raised $24M. Letta raised $10M. Supermemory raised $3M. A new "AI memory" repo hits GitHub trending almost every week, usually built by someone over a weekend. And every major AI platform — Claude, ChatGPT, Gemini — has shipped some version of built-in memory. Everyone's building memory. The question is: what kind, for whom, and can you actually read it? ## The quick overview | | Basic Memory | Mem0 | Letta | Supermemory | Weekend projects | | ------------------------------ | ------------------------ | ------------------------- | ------------------ | --------------------------- | ---------------- | | **What it is** | Knowledge base for you | Memory API for developers | Agent framework | Memory infra for developers | Varies | | **You can read what's stored** | Yes — it's just files | No | Partially | No (it's a backend service) | Rarely | | **Open source** | AGPL | Partial | Apache 2.0 | No | Usually | | **Funding** | Bootstrapped, profitable | $24M VC | $10M VC | $3M VC | $0 | | **Cloud option** | $19/mo | Enterprise pricing | Enterprise pricing | Pay-per-query API | N/A | | **Primary interface** | Files + knowledge graph | API | Agent framework | API | Varies | ## Basic Memory: your memory, in files you own Basic Memory stores everything as plain text files. When your AI writes a memory, it creates a note you can open in any text editor. Notes connect to each other through semantic links, forming a knowledge graph that grows over time. **What we do well:** - **Transparency.** You can read, edit, and delete anything your AI "knows" about you. Open a folder, read the files. - **Bidirectional.** You and your AI read and write the same files. You can edit a note and your AI will see it. Your AI writes a note and you can read it. - **Portable.** It's plain text. If Basic Memory disappeared tomorrow, you'd still have useful, readable files. Try that with an API. **Where we're honest about limitations:** - We're not an enterprise platform. No org-wide user management (yet). - We're a smaller team than our VC-funded competitors. **Cloud pricing:** $19/month for Basic Memory Cloud. ## Mem0: the developer memory API Mem0 has raised $24M and built a popular developer ecosystem. Their approach is a memory API — developers send data in, it stores and retrieves memories, and they integrate it into their apps. **What Mem0 does well:** - **Developer ecosystem.** Extensive documentation, lots of integrations, a large community. - **Simple API.** `mem0.add()` and `mem0.search()` — clean and fast to integrate. - **Enterprise features.** If you're building a product that needs managed memory infrastructure, they're built for it. **The tradeoffs:** - **Opaque by design.** There's no user-facing interface to see what's stored. It's a black box for developers to build on top of. - **VC dynamics.** $24M in funding means Mem0 needs to become a very large business. That shapes product decisions. - **Users of apps built on Mem0 have no visibility** into what the app remembers about them. ## Letta: the agent framework with memory Letta (formerly MemGPT) started as a research project exploring how to use an LLM's context window as a virtual memory system. They've since evolved into a full agent framework with persistent state. **What Letta does well:** - **Research-driven.** They think deeply about how memory should work for agents. Their MemGPT paper was genuinely innovative. - **Full agent framework.** If you're building complex AI agents that need state management, Letta provides serious infrastructure. **The tradeoffs:** - **It's an agent framework, not a memory tool.** If you just want persistent memory, it's a lot of machinery. - **$10M VC-funded.** The product roadmap serves investor returns as much as users. - **Still abstracted.** Even as they move toward file-based approaches, memory is several layers away from "open a folder and read markdown." ## Supermemory: backend memory infrastructure Supermemory is a B2B infrastructure play — a memory API that developers embed in their products to power AI features. Think of it like a database service, but for AI memory. **What Supermemory does well:** - **Infrastructure focus.** Fast, scalable memory retrieval built on Postgres and a vector engine. - **Developer-friendly.** Clean SDKs, works with OpenAI, Anthropic, and other providers. **The tradeoffs:** - **Not a consumer product.** End users of apps built on Supermemory have no way to see, edit, or export what's stored about them. - **VC-funded ($3M).** Same dynamics as the others. - **Closed source.** You're dependent on their infrastructure. ## Weekend projects and open-source experiments Every few weeks something new hits GitHub trending — a weekend build that adds memory to Claude or ChatGPT, usually by storing conversation snippets in a vector database. Some are clever. Most solve a narrow problem. These are worth watching, but come with real tradeoffs: no ongoing maintenance, no sync, no knowledge graph, and often no way to manage what's stored once you've accumulated it. ## The fundamental question Here's what it comes down to: **can you read what your AI knows about you?** With Basic Memory, the answer is yes — always. Your memory is a folder of plain text files. You can open any of them, edit them, delete them, or take them somewhere else entirely. With Mem0, Letta, and Supermemory, memory is managed *for* developers. They interact with it through APIs. End users interact with whatever interface the developer built — and the actual storage is invisible. Neither philosophy is wrong. But they're solving different problems for different people. Mem0 and Supermemory are infrastructure for developers building apps. Letta is infrastructure for developers building agents. Basic Memory is for you — the person who wants to remember things across conversations, own what you know, and actually be able to read it. ## Who should use what **Choose Basic Memory if:** - You want to own your memory as readable files - You use Claude and want MCP-native memory that just works - You value transparency - You don't want to depend on a VC-funded company's roadmap **Choose Mem0 if:** - You're a developer building an app that needs memory as a service - You need enterprise-grade managed infrastructure - Opacity is fine — your users don't need to see what's stored **Choose Letta if:** - You're building complex AI agents that need state management - You want a full agent framework, not just memory - You're doing serious research on memory architectures **Choose Supermemory if:** - You're a developer who wants fast, scalable memory infrastructure as a backend service - You're building at enterprise scale and cost efficiency matters **Watch the weekend projects if:** - You're curious and want to experiment - You're a developer who wants to understand how memory systems work under the hood ## Our perspective We're not trying to be Mem0 or Letta. We're not building infrastructure for other developers to build on (though we might consider expanding in that direction soon). We're building for the person who wants their AI to remember things — and who believes they should be able to read, edit, and own what it remembers. The memory space is big enough for all of these approaches. But we think the future of personal AI memory is transparent. Plain text has outlasted every proprietary format in computing history. It'll outlast whatever comes next too. # Beer, Bitching, and the Birth of Basic Memory ## Here's the Problem Paul and I are old friends who catch up over beers every week. We both fell hard into the world of AI at the same time last year. He came to it as a professional developer with many years of experience, and I came to it as a bemused consumer. We were both firmly Team Claude at the time, and our conversations about AI circled the same fascinations and frustrations, but as models evolved and more and more kinks were resolved, one complaint remained constant: the lack of true continuity. Between praising what would be achieved as we pushed the capabilities of careful prompting paired with Claude's Projects and Project Knowledge, we kept circling back to the same core issue. You know how it goes. In Claude, it was a question of running out of prompts in overlong chats and using those final prompts to ask Claude to build summaries to paste into the next chat. No matter how many times we asked him to "be more exhaustive," new chats inevitably had a noticeably different texture and still required a lot of catching up. GPT was the same. Granted, their memory system is large and growing, yet the core problem isn't resolved. Have you ever looked at Chat's memory settings? I have, and, while their memory is incredibly helpful, it remains imperfect and incomplete. What it chooses to remember and how it chooses to remember (in deleteable but non-editable files) inevitably causes weird hiccups and miscommunications. "No, Chat, remember you LIKED this idea 20 minutes ago. Now you hate it? You gotta be kidding me." Even the very best chats are eventually forced to their conclusions, and the context---along with an ineffable textural quality developed by any given chat---vanishes with them. In a word the experience sucks. What's more, each AI conversation is siloed in its own ecosystem. I can have a terrific, helpful exchange with Claude that Chat will never be able to chime in on. And vice versa. No amount of personal intervention and clever prompting resolves it. At one point, I was working on a nonfiction book proposal, for which I was continually starting new chats called "This is the one" and "No, this one." I was repeatedly cutting and pasting context, inevitably screwing up some of my uploads and ending up with dated sections, digging through past chats and downloads to get back on course. I wanted to simply ask Chat or Claude, "Hey, do you remember how we even came up with this section?" Or, "Wasn't there a better version of this before?" But, hell, they knew even less than I did. I've long since learned to ignore anyone who starts a sentence with the words "Why don't they just..." But, seriously, why didn't someone just fix this? Then, while I complained, Paul did "just" begin to work on a solution. And he stuck with it. For months. Each new version was mine to test drive. I was hooked from V 0.1. The introduction of Basic Memory instantly changed my AI workflow, eliminating the frustrations I spent months groaning about. ## Okay, but what does it actually DO? ### Here's the Solution Here's how it goes: I'm chatting with Claude about my book proposal, and I ask it to save some notes about our conversation. Let's say we have several separate chats. One about market analysis, comp titles, and target audience, another about how best to summarize the book for the synopsis, and then another about the author bio. A few days later, I sit down and want to continue working on the pitch, but I can't really remember where things stand. So I say, "Hey, can you read our notes and see what still needs to be done on the book proposal and where we left off? I'm kind of lost." And Claude says, "Sure, gimme a sec while I check it out." Then it tells me exactly what's going on, creates a note to mark the level set, and we carry on. He's locked and loaded with everything we've discussed---ready to pick up any thread as if the conversation never stopped. If you ever struggle to get back on track, it's kind of incredible to experience. I'm reluctant to raise this example because Paul has been extremely scrupulous about all things privacy-related, but I imagine it as if an extremely discerning court reporter is listening in on all our chats. But instead of keeping a transcript, the court reporter knows exactly what information they will need to remember to patch together a full picture to a future version of itself and me. But there is no third party listening in. Claude (or Chat or whatever you're using) is the one writing the notes, which means it's always asking itself, "How am I going to explain this not just to Drew, but to myself?" Here's what's cool about the notes. You can read them too. They're just notes written in Markdown that anyone can read. It's not a scrambled JSON file or an endless scroll of some unreadable programming language. Each note exists as a nicely formatted, well structured document written in the kind of language you two would use in your chats. Not only that, you can change the notes anytime you want. Better yet, thanks to the most recent update, Claude can edit the notes too. Here's something that happened a while back. Claude and I were going over all the different projects I've discussed with him and talking about the ways in which they're thematically linked. It was a totally unimportant conversation that had nothing to do with anything, but it created some notes that ended up linking projects in a way that was just not right. It was purely my mistake. Claude would never have connected one business idea I had with a horror novel concept I was tossing around if I hadn't asked him to find the connection. But the note stuck, and every time I wanted to talk about that business idea, Claude would say, "And it seems like this project is also connected with a horror concept. That's interesting." I could have gone in and changed that note myself. It would have been easy. I just never did, and I rolled my eyes every time the supposed connection popped up. But the last time it came up in our conversation, thanks to the latest update, I just said, "Hey, that connection doesn't actually exist. It was just a dumb thought experiment. Can you please get rid of any connections/notes that might make you think they're connected?" And it did exactly that with no problem. It really does feel like a second brain that you're both working from. Picture a jar with scraps of paper bearing all the information you've ever discussed with AI. It's a massive pain in the ass to go looking through the jar of scraps and dig up every conversation on a certain topic. But Claude, with the help of Basic Memory, can do it on his own. And it's not just for writing or business planning or brainstorming. Paul uses it for coding every day. It's as versatile as any AI use case you can imagine. Every AI conversation finally feels like a continuation---not a reset. That changes everything. # We Benchmark in the Open Most AI memory products don't publish benchmarks. The ones that do tend to cherry-pick metrics, use proprietary evaluation setups, or — in at least one case — [get caught inflating their numbers](https://github.com/getzep/zep-papers/issues/5){rel=""nofollow""}. We decided to do it differently. We built a standalone, reproducible benchmark suite, ran it against an academic dataset, and published everything: the code, the results, the methodology, and the gaps. Here's what we found. ## The Dataset: LoCoMo [LoCoMo](https://snap-research.github.io/locomo/){rel=""nofollow""} is an academic benchmark from Snap Research designed to test long-conversation memory systems. It's 10 multi-session conversations with 1,982 questions across five categories: - **Single-hop** — straightforward fact recall ("Where does Alice work?") - **Multi-hop** — connecting facts across conversations ("Who works at the same company as the person who likes hiking?") - **Temporal** — time-sensitive reasoning ("What was Bob's job before he switched in March?") - **Open-domain** — broad knowledge retrieval - **Adversarial** — questions designed to trip up memory systems It's the same benchmark used by Mem0, Zep, MemMachine, and others. Common ground for comparison. ## Our Results Basic Memory v0.18.5, running entirely local on SQLite with local embeddings. No cloud APIs. No external services. | Metric | Score | | ---------------- | ----------- | | **Recall\@5** | **76.4%** | | **Recall\@10** | **85.5%** | | **MRR** | **0.658** | | **Mean Latency** | **1,063ms** | By category (Recall\@5): | Category | Score | | ----------- | ----- | | Open-domain | 86.6% | | Multi-hop | 84.1% | | Adversarial | 67.0% | | Temporal | 59.1% | | Single-hop | 57.7% | We're strong on open-domain and multi-hop retrieval. The knowledge graph structure helps here — connecting facts across conversations is literally what a graph does. We're weaker on single-hop and temporal queries, and we know why. ## What's Working **Multi-hop retrieval (84.1%)** is our standout. Questions that require connecting information across multiple conversations play to our architecture's strength. When you write a note about Alice's job and another about Alice's hiking trip, Basic Memory's relation graph links them. A query about "Alice's hobbies and career" traverses that graph. **Open-domain (86.6%)** is strong because hybrid search — combining keyword matching with semantic similarity — handles broad queries well. The keyword side catches exact terms; the vector side catches related concepts. **Fully local execution** matters more than it sounds. Every query runs against a local SQLite database with local embeddings. No network calls, no API keys, no per-query costs. The 1,063ms mean latency is end-to-end on consumer hardware. ## What's Not Working (Yet) **Single-hop (57.7%)** is our biggest gap. This is basic fact recall — the kind of thing that should be easy. The issue is architectural: we store full conversations and rely on chunk matching, while competitors like Mem0 extract atomic facts before storing. Their approach creates precise, granular memory units. Ours preserves full context but makes pinpoint retrieval harder. **Temporal (59.1%)** suffers because we don't yet distinguish between "when a note was created" and "when the event it describes happened." If you write today about a meeting that happened last Tuesday, Basic Memory timestamps today's date. Temporal queries need the event date. This is a solvable problem — we just haven't solved it yet. ## The Comparison Problem Here's where we need to be honest about something the industry mostly isn't. There are two ways to evaluate memory systems: 1. **Retrieval metrics** — Did the system find the right document? (Recall\@K, MRR) 2. **LLM-as-Judge** — Given what was retrieved, did an LLM produce the correct answer? (Binary score from GPT-4o) We currently measure (1). Most published competitor numbers use (2). **These are not directly comparable.** A system with perfect retrieval but bad prompting scores high on (1) and low on (2). A system with mediocre retrieval but excellent answer generation could score higher on (2) than a system with better retrieval. They're measuring different things. Published LLM-as-Judge scores from competitors: | System | Overall Score | | --------------- | ------------- | | MemMachine | 84.9% | | Mem0 (graph) | 68.5% | | Mem0 | 66.9% | | Zep (corrected) | 58.4% | | LangMem | 58.1% | | OpenAI Memory | 52.9% | We can't put our number in that table yet because we haven't run the LLM-as-Judge step. We're adding it. When we do, the results go in the same public repo alongside everything else. We could have estimated where we'd land, or presented our retrieval metrics alongside their answer metrics and hoped nobody noticed the difference. We chose not to. ## The Zep Incident Speaking of benchmark honesty: Zep originally published an 84% LoCoMo score. Mem0's CTO found that Zep had included adversarial category answers in the numerator while excluding adversarial questions from the denominator — inflating their number significantly. The corrected score is 58.4%. This is why we publish the code. Every query. Every result. The exact commands to reproduce the run. If our methodology is wrong, you can find it and tell us. ## What We're Improving Based on these results, we're working on: - **Better observation extraction** — more atomic facts per conversation, closing the single-hop gap - **Temporal indexing** — separating document dates from event dates - **LLM-as-Judge evaluation** — so we can compare apples-to-apples with published numbers - **Cloud benchmarks with OpenAI embeddings** — local embeddings are good; cloud embeddings should be better Each improvement gets benchmarked before and after, on the same dataset, with the same methodology. No "trust us, it's better now." Numbers or it didn't happen. ## Reproduce It Yourself The entire benchmark suite is open source: ```bash git clone https://github.com/basicmachines-co/basic-memory-benchmarks cd basic-memory-benchmarks uv sync --group dev uv run bm-bench datasets fetch --dataset locomo uv run bm-bench convert locomo uv run bm-bench run retrieval --providers bm-local ``` Every run produces a manifest with provenance metadata: git SHA, BM version, dataset checksums, provider configurations. Full reproducibility, not "we ran it once on a good day." [Benchmark repo →](https://github.com/basicmachines-co/basic-memory-benchmarks){rel=""nofollow""} ## Why This Matters Benchmarks are how you know if a product actually works, or if it just has good marketing. The AI memory space is full of big claims and few receipts. We'd rather show you a 76.4% that you can verify than an 85% that you can't. And when we improve that number — and we will — you'll be able to see exactly what changed and why. That's the same philosophy behind the product itself. Plain text you can read. Results you can reproduce. No black boxes. # The Caveman Evolution of Basic Memory ### Forward This is the second time I have written this post. The first time, after working for hours recalling and writing, the note I was writing was lost because of a bug in the Basic Memory Cloud web editor. Sometimes things are hard. I was determined to write it myself too. I did use AI to edit (my typing is terrible), and help dig out relevant commits and make sure the timeline is accurate. I have jokingly called this piece "The Caveman Evolution of Basic Memory", because it captures some of the story from primitive, simple beginnings, and how it has evolved over time. ### Finding some inspiration When I first started working on what would become Basic Memory, the MCP spec had just been released. MCP (the Model Context Protocol) is the standard that lets an AI app call out to external tools — in practice, it's how you give an AI new abilities. I was using Claude Desktop and wanted to save info from my chats locally, not copy/paste back into the project knowledge all the time. The big pain I was feeling was starting over from zero with every new chat. Further, chats would suddenly just stop when you reached the context limit and you were SOL. This is still a pain, to be honest, but things have gotten a lot better, compaction works ok for the most part, AI-native memory remembers useful things most of the time. But way back then, in late 2024, things were pretty raw. I had a coding project I was working on, a variation of shadcn UI components, but written with HTMX and Alpine.js. My idea was to make frontend development suck less for apps I wanted to build. I have always hated working in React. It makes zero sense to me to this day. What I discovered while implementing a bunch of these components is that AI could write them much better and faster than I could. I was literally copy/pasting code snippets in and out of the chat window and my IDE. To manage this, I had a bunch of Markdown notes in Obsidian and I was copy pasting back and forth. I started using Claude Desktop when it came out, and it seemed to understand the gist of what I was trying to do very well. Soon thereafter, I saw the memory MCP ({rel=""nofollow""}) and thought, I want "that". I could see that there might be some way I could use it to get out of my copy pasting long context over and over. So, I started doing what any developer would do, poking through the source code and stealing ideas. Instead of JSON though, I wanted Markdown, because I wanted to edit the files myself. That basic idea grew into what Basic Memory still is today, a bunch of Markdown files that get parsed and indexed into a "knowledge graph". I was already using Claude to write code, but still typing a bunch myself in the IDE. Then I started using the filesystem MCP and was like "holy crap, AI can do this faster than I can". So now I really wanted to make something that AI could really use to store memory so I could use it all the time. ### Ch. 1 - Local-first, plain text, stdio, because that's what existed (Dec 2024) **From the git log:** - First commit [f95a8562](https://github.com/basicmachines-co/basic-memory/commit/f95a8562){rel=""nofollow""} (2024-12-02). - First MCP server [18dd8796](https://github.com/basicmachines-co/basic-memory/commit/18dd8796){rel=""nofollow""} (2024-12-08): low-level `mcp.server.Server` + `stdio_server()`; tools reached straight into the DB via `deps.get_project_services()`. No API layer. Recovered artifact — `basic-memory.md` at the repo root had mermaid architecture sketches by 2024-12-05, three days after the first commit ([view the file at that commit](https://github.com/basicmachines-co/basic-memory/blob/18dd8796/basic-memory.md){rel=""nofollow""}). ```mermaid graph TD subgraph "Frontend" NB[Notebook Interface] VIZ[Visualizations] ED[Editors] end subgraph "Backend" API[FastAPI] DB[(SQLite)] MCP[MCP Server] end NB -->|HTMX| API VIZ -->|Updates| API ED -->|Changes| API API -->|Query| DB API -->|Context| MCP MCP -->|Updates| DB ``` #### The Plan evolves There were some ideas I had clarity about. I wanted Basic Memory to be based on plain text, but it took some experimentation and iteration to figure out how that would work. Day one already had the principle ([cbf366a7](https://github.com/basicmachines-co/basic-memory/commit/cbf366a7){rel=""nofollow""}, 2024-12-02) — a comment in the very first service code lays it out, **"filesystem is source of truth"**: 1. Write to filesystem first 2. Update database indexes second 3. Database is treated as disposable/rebuild-able index But the flow was one-directional — the app wrote files as output (the Dec-05 sketch above even shows `DB -->|generate| MD`). The reverse direction — humans edit files anywhere (Obsidian, git, whatever) and the app detects the changes and parses them into the graph — landed a couple of weeks later with `file_sync_service` ([a4c1989c](https://github.com/basicmachines-co/basic-memory/commit/a4c1989c){rel=""nofollow""}, 12-19). Then I added proper markdown parsing of the file content ([c9fec7ab](https://github.com/basicmachines-co/basic-memory/commit/c9fec7ab){rel=""nofollow""}, [8b26162a](https://github.com/basicmachines-co/basic-memory/commit/8b26162a){rel=""nofollow""}, 12-21). The Entity table grew a `checksum` column for change detection. By v0.1.0, `basic-memory sync --watch` ran a file watcher so edits made outside the app were picked up too. #### Index for fast lookups Now that the files were the canonical truth, the db index could be a derived artifact — something you can throw away and rebuild from the files in seconds. This principle ended up surviving every architecture that followed. Ten months later, deep in the cloud storage struggles, we would write the same sentence in a spec: > "The SQLite database is just an index cache… It can be rebuilt in seconds from the source markdown files." The sync and indexing code itself would be rewritten several times over, local and cloud — but that's a later chapter. The first MCP spec (2024-11-05) defined two transports: stdio and HTTP+SSE. Stdio was just the only one that mattered in practice (Claude Desktop only spoke stdio). I had to read that spec (myself) at least ten times before I understood what a "server" or a "host" was and just where and how the runtime worked. Stdio is at once very powerful (hello Unix CLI toolset) and also very limiting (for example error handling). But being able to plug into an AI app (what we now call a harness) was super cool. Since all of this was new, I started looking at the Python SDK examples and was like, WTF? This is terrible. I built the first version with the low-level SDK anyway. Luckily, a couple of weeks in, I found FastMCP, which had just come out, and I started using it, since it had a similar usage flow to FastAPI, which I was already a big fan of. #### Markdown format Working with Claude, I came up with a basic structure to re-create the simple data model from the Memory MCP. Entity, Observation, Relation. Looking back now, this was a real missed opportunity to rename "Entity" to something better. **Entity** An entity is a node in the knowledge graph. This became a Markdown note, with frontmatter and text. ```text --- title: An Entity is a Markdown file permalink: a-slug-for-the-entity type: anything tags: ["whatever", "you", "want", "here"] --- # About an Entity The rest is just plain text Markdown ``` **Observation** An observation is a fact about an Entity. They always refer to exactly one Entity. I wanted something simple to record these. In Markdown, it's really easy to make lists, so I just added a special `[category]` marker to a regular Markdown list to record Observations with a category type. ```text - [fact] an Observation is a list item with a string in brackets at the beginning ``` **Relation** A relation is a directed connection between two Entities: it has a type, a source, and a destination. The source is the Entity note which contains the Relation. The destination is the Entity referenced. Relations are \[\[wikilinks]]; they can also be written as a Markdown list item to declare the type. ```text - related [[Some other Entity]] ``` The value inside the wikilink is matched in a few ways — by exact string or by fuzzy text search — so links don't have to be exact. #### Data model The data model was deliberately simple too, just those three tables and some properties. ```mermaid erDiagram ENTITY ||--o{ OBSERVATION : has ENTITY ||--o{ RELATION : from ENTITY |o--o{ RELATION : "to (nullable)" ENTITY { int id PK string title string entity_type string permalink UK string file_path UK string checksum json entity_metadata } OBSERVATION { int id PK int entity_id FK string category text content json tags } RELATION { int id PK int from_id FK int to_id FK "null until resolved" string to_name "raw wikilink text" string relation_type } ``` (This is the actual v0.1.0 schema. Note `to_id` is nullable and `to_name` keeps the raw \[\[wikilink]] text — an unresolved link just waits until a matching entity shows up.) I added full text search and indexed the title and Markdown body. Even with just these things it was pretty clear that search, combined with a few hops through the knowledge graph was a pretty powerful combo. The first operation I implemented to load context for `build_context` was: - search via full text search - for each top result - find the next related results - include a small summary and id for each With this, the AI could search iteratively with a few calls and find a really wide set of notes, then choose which ones looked most relevant. This is almost like "Graph RAG" without the RAG (there were no embeddings yet). #### Prompting Patterns The pattern I was figuring out was that the tools themselves don't have to be fancy, or "intelligent". The AI model, using simple tools, can decide how to call them. Doing small simple things lets the model be the star. The better the model can access the knowledge base, the more useful it is for the user. This led to a few other patterns I'll point out. **Be helpful** When there were no results found, instead of returning a terse return code, the tools prompted the model to try other operations, or prompt the user for a possible next action. This keeps the AI from getting stuck or giving up too quickly. The tools were really an interface to prompt the AI more effectively. This is now called "context engineering", but it's very natural if you think about it. For the AI, it's all just context. Here's what `read_note` returns when it can't find a note (from `src/basic_memory/mcp/tools/read_note.py` — the pattern dates back to the earliest versions): ```text # Note Not Found: "coffee brewing methods" I couldn't find any notes matching "coffee brewing methods". Here are some suggestions: ## Check Identifier Type - If you provided a title, try using the exact permalink instead - If you provided a permalink, check for typos or try a broader search ## Search Instead Try searching for related content: search_notes(project="main", query="coffee brewing methods") ## Recent Activity Check recently modified notes: recent_activity(timeframe="7d") ## Create New Note This might be a good opportunity to create a new note on this topic: write_note(project="main", title="Coffee Brewing Methods", ...) ``` The "error" is really a menu of next moves for the model. **Keep the flow going** Give the model an idea of what to do next. When the search results return, the prompts returned to the model include instructions about reading the full results. For example, the search prompt appends this right after the result list (from `src/basic_memory/mcp/prompts/search.py`): ```text ## Next Steps Based on these 5 results, you can: 1. **Read a specific note** - Use `read_note("permalink")` to see full content 2. **Build context** - Use `build_context("memory://path")` to see relationships 3. **Refine search** - Use `search_notes("refined query")` to narrow results 4. **Check recent activity** - Use `recent_activity(timeframe="7d")` for recent changes ``` **Be liberal with inputs** This is an [old programmer saying](https://en.wikipedia.org/wiki/Robustness_principle){rel=""nofollow""} (Postel's law), but it's especially true with LLMs. If you make them pass in complex JSON, they will most likely screw it up a few times. This wastes tokens and slows everything down. This leads to a lot of parsing on the server end, but that is preferred because you can test it easily. At this point, I felt like I had enough to share with more people. I had a few friends I set up with the v0.1 basic-memory MCP server and was shocked that without much help, it just started working when people used it with Claude. Now, you didn't need to manage a bunch of stuff in Claude Projects. You could just start new chats and reference previous topics without having to re-explain all the time. I think a big part of this working is that LLMs, particularly Claude, are good at "seeing", or more accurately inferring, the context between two topics. Using Basic Memory, they had just enough tool support to find more data when needed and pull it into the context window. It was far from perfect, but it was a good start. Here's how the basic system worked. ```mermaid flowchart LR AI[AI
Claude Desktop] HU[Human
Obsidian, any editor] MD[Markdown files
source of truth] DB[(SQLite
rebuildable index)] AI -->|MCP: write_note| MD HU -->|edits| MD MD -->|sync: checksum diff → parse| DB AI -->|MCP: search_notes, build_context| DB DB -.->|results point back to| MD ``` ### The decision the whole story hangs on (Dec 2024) **From the git log:** - 2024-12-14: FastAPI app born ([1ed4c72f](https://github.com/basicmachines-co/basic-memory/commit/1ed4c72f){rel=""nofollow""}) AND the MCP server rewired to stop touching the DB — forwarding every call to that app **in-process via httpx ASGITransport** ([052ee403](https://github.com/basicmachines-co/basic-memory/commit/052ee403){rel=""nofollow""}). - Client factored into `mcp/async_client.py` ([353342a5](https://github.com/basicmachines-co/basic-memory/commit/353342a5){rel=""nofollow""}, 12-25); old low-level server deleted ([7322bb53](https://github.com/basicmachines-co/basic-memory/commit/7322bb53){rel=""nofollow""}, 2025-01-18); **v0.1.0 ships 2025-02-07** ([7c6ed53a](https://github.com/basicmachines-co/basic-memory/commit/7c6ed53a){rel=""nofollow""}). - Because tools spoke to an ASGI app rather than a database, the same tools could later point at a remote API. That is the seam. The decision has its own napkin drawing. I found it in my own knowledge base — a design note dated 2024-12-13, the day before the decision commits landed, stored inside Basic Memory itself. The connector label — "ASGI Transport" — and the dependency injection box are both already there: ```mermaid graph TD subgraph Clients CLI[CLI Client] MCP[MCP Server] WEB[Web Client] end subgraph "FastAPI Layer" FA[FastAPI App] DI[Dependency Injection] EP[Endpoints] end subgraph "Core Services" MS[Memory Service] ES[Entity Service] RS[Relation Service] OS[Observation Service] end subgraph Storage DB[(SQLite)] FS[File System] end CLI -->|ASGI Transport| FA MCP -->|ASGI Transport| FA WEB -->|HTTP| FA FA --> DI DI --> EP EP --> MS MS --> ES MS --> RS MS --> OS ES --> DB ES --> FS ``` Backing up a couple of months — this decision actually came in week two, before v0.1 ever shipped. One thing missing from FastMCP though was the dependency injection (DI) in FastAPI. I've seen it get a lot of hate, but in my experience, writing factory code without DI really sucks, makes you write a ton of boilerplate, and can easily end up a tightly coupled mess. I've seen this in just about every language I've programmed in. Also, FastAPI is well understood and has some really great patterns for testing. As I started to put the basic code outlines together for Basic Memory, it was pretty clear that what I mostly needed was plain ole service code, some file parsing, file IO and database code. All very non-AI. The only real AI part of the app was in the tools and even that was mostly Pydantic (I have since come to understand various patterns to make the tools more AI friendly and effective, see "Prompting Patterns" above). As I was building the db layer, and business services, I kept thinking "this would be so much easier in FastAPI". I considered making an http backend service and having the tools call to a local endpoint, but I was worried that since MCP was very new, and still difficult to install and configure, that would be more than people would want to deal with. Running a daemon service locally is a chore only a developer would likely be willing to endure. So, I made an unconventional decision, one that I really hadn't seen anyone else doing in a real app. I decided to follow the pattern typically used for testing a FastAPI app - create an app instance and pass requests to it through an in-memory ASGI client. It worked great for tests, so why not for real life? I started doing it, and it worked really well. In fact it's still the pattern used in Basic Memory today. ```text AI (Claude Desktop, etc.) │ │ MCP over stdio ▼ ┌────────────── one process ───────────────┐ │ │ │ MCP server (FastMCP) │ │ └── tool: write_note(...) │ │ │ │ │ │ httpx AsyncClient │ │ │ ASGITransport(app) │ │ │ no socket, no port, │ │ │ no daemon │ │ ▼ │ │ FastAPI app (in memory) │ │ └── /knowledge /search /memory │ │ │ │ │ ▼ │ │ services ──► SQLite index │ │ ──► Markdown files │ │ │ └──────────────────────────────────────────┘ ``` It works like this: - Tools get called via MCP by an AI agent or stdio call - A tool contains an httpx client configured to call an in-memory FastAPI endpoint - The tool transforms its args into an http request and calls one or more endpoints, and handles the response - The tool then outputs the response to the AI in a format as needed: markdown, text, json The benefits of this kind of setup became: - Most of the application is just a FastAPI app: services, data repositories, db models, pydantic schemas - This part of the application is really easy to test without needing any AI setup - Tool function implementations were very small and just composing inputs and outputs - It naturally fit into how you might build a CLI client to call a remote service too, so adding CLI support was easy It did come with some extra overhead of doing Pydantic twice in the flow, once for tool args, and another time for the in memory api call, but in practice this was not the slow part. File parsing and IO were always the bigger bottleneck. And it turns out that simpler tool args work better than complex json anyway (to make the same point again). I had planned to figure out a way to leverage this tool-to-endpoint proxy pattern for a cloud service. At that time in early MCP days, the only option for remote calls was SSE. This came with a bunch of problems, because it meant that the connection was stateful and connections had to be routed to a particular service instead of load balancing like you would typically do for a web application. But before I could get far enough here, they added streamable HTTP to the MCP spec (the 2025-03-26 revision, which also added the OAuth 2.1 authorization framework). ### Going Pro I'll take a quick detour and mention that between the time when I had the basic-memory MCP working locally and the Basic Memory Cloud (described below), I made an aborted attempt at a standalone application, Basic Memory Pro. The idea was to "break out of the box" of just being an MCP tool and control the entire UX for the application. This took the form of a Tauri (Electron in Rust) application shell with a React web editor and UI shell. The basic-memory app ran locally via a sidecar and exposed the FastAPI endpoints (the same ones the tools used) to the frontend app. I spent about a month on this and got to an ok-ish place. It was primitive, but using shadcn and Claude to code the frontend got me pretty far. The experience left me with some lessons learned. **Only break one law at a time** There's an old saying, "Only break one law at a time", that I think translates to programming - only do one thing you aren't familiar with at a time. Trying to build a complex UI flow in React (typescript), in Tauri (Rust), for multiple platforms was just too much extra cruft to manage. The version of Tauri I was using (2.0, released October 2024) was newer, and Claude preferred coding in the old version. I wasn't familiar enough with Rust to review the code for correctness and churned a lot debugging. **Packaging is hell** Also, trying to bundle all of this together and make it work across platforms is non-trivial, to say the least, involving native packaging, uv for python, etc. Getting stuck at the last mile is the worst way to end a trip, but sometimes you just have to listen when the world is telling you something. About this time, the MCP SDK got another rev (2025-05-08), this time enabling streamable HTTP and OAuth. This led me to re-evaluate my plans, in light of the troubles with the Pro app and consider a cloud product. ### The payoff + the caveman cloud (Jun–Aug 2025) **From the git log:** - The founding decision cashes in: core's `create_client()` starts branching **local-ASGI vs cloud-HTTP** on config (`[473f70c9](https://github.com/basicmachines-co/basic-memory/commit/473f70c9)`, 2025-07-07). - Founding cloud shape (`BASIC_MEMORY_CLOUD_v2.md`, 2025-06-15): **one Fly app per tenant**, encrypted Fly volumes, a separate `apps/mcp` gateway (SSE) + OAuth server. - Control-plane DB moved Supabase → Neon (`ee88ad110`, 2025-08) — separate from and earlier than per-tenant Neon. - Queue engine at this point: **DBOS**. Here it is in eleven lines (`src/basic_memory/mcp/async_client.py`, [473f70c9](https://github.com/basicmachines-co/basic-memory/commit/473f70c9){rel=""nofollow""}, 2025-07-07 — condensed; full version in the commit): ```python def create_client() -> AsyncClient: config = ConfigManager().load_config() if config.api_url: # Use HTTP transport for remote API return AsyncClient(base_url=config.api_url) else: # Use ASGI transport for local API return AsyncClient( transport=ASGITransport(app=fastapi_app), base_url="http://test" ) ``` **From the notes:** - The cloud was designed inside Basic Memory itself. The founding architecture note still lives in my knowledge base — a Basic Memory note, frontmatter and all (May 2025). The first drawing: React frontend, a Platform API / Basic Memory API split, Supabase Postgres for tenant management, **Turso LibSQL** for the knowledge DB, and **git-backed file storage** on Fly. - Turso was in the very first sketch — it would be spiked for real in September and abandoned in October (a later chapter). The git-backed storage idea kept echoing back later too. - The cloud repo's first commit is 2025-05-12; the design notes were imported a week later (`a0f3b3b9d`, 2025-05-20) — already into a `docs/archive/` folder, which tells you how fast the ideas were churning. - The shape that actually got built arrived a month later: `BASIC_MEMORY_CLOUD.md` (`46f0d4563`, 2025-06-14), then `BASIC_MEMORY_CLOUD_v2.md` (`4a5e761e1`, 2025-06-15) — one Fly app per tenant. So, I started thinking about what shape a Basic Memory Cloud could take. There were a few ideas to wrap my head around. **Local First to Privacy First** First of all, being in the cloud meant that things were no longer going to be "Local First". This had been a raison d'être until that point, so it required a shift in mindset. The truth is that local is cool, and gives a lot of benefits (privacy, ownership, control), but also has some real limitations. I really wanted to be able to use Basic Memory for every AI, and every surface: Claude Desktop, Claude Code (when it was released), mobile, but also ChatGPT. Only having notes local to one computer leaves you to manage all the syncing and sharing. Some people are ok with that, but I knew most people weren't. Even I couldn't be bothered to do it, and I knew how to make it all work. So, I tried to translate the principles for "Local First (only)" to a cloud context. **Privacy First** If I couldn't do local first, at least I could try to make things as private as possible. My goal was to find some sort of completely encrypted way to store notes (zero trust), but as I learned, this is also not really practical. Sharing means compromising control, and there are always tradeoffs. But I could design the cloud architecture to minimize them. **Tenant isolation** When designing a multitenant (tenant means customer in SaaS terminology) cloud architecture, you can either co-locate data, meaning keep it all together, or keep each customer completely isolated. There is no right or wrong answer, each has trade-offs. The easiest way tends to be co-locating, because managing services or data per customer can be a challenge. Nevertheless, after looking into some of the newer cloud hosting platforms, particularly fly.io, I decided to bias towards complete isolation. This is something that would evolve, in practice, but customer data has and will always be completely isolated. **Cost effective** The other key factor in managing a cloud service is designing for cost. Running servers in the cloud costs real money. Storing data in the cloud can also get expensive quickly. You even have to consider bandwidth and IO costs. You pay for all of it, and therefore cost has to factor heavily into your design, or you won't have a viable business. **Now we are in business** If I could get something working so running Basic Memory in the cloud was easier than running locally, and provided more features, I was hopeful I could find customers. After making a proof of concept, and thinking this could really work, I needed to have a proper business. Going into business is no small effort, and I knew it was more work than I wanted (or was able) to do on my own. I needed partners. Forming a team like Voltron is a story unto itself. The tl;dr is that I already had the crew lined up. I just had to figure out how everything was going to work. **What type of business do we want to be?** I've had a pretty long run as a working software developer (engineer). From consulting, to big companies, to startups, acquisition, promotion, manager, to getting laid off. I can hardly count how many times I've been laid off in my career. I know it takes two hands. So when I thought about starting my own business, I had a lot of my own ideas. I had gotten as close as I had come to AI psychosis, in a conversation with Claude about how it could all work, producing several revisions of what we called the "manifesto". It's a bit too cringy to share, but there are some points I wanted to make sure were included: - **Tools shape thought** — keep tools simple but powerful; let them enhance rather than replace human capabilities - **Knowledge belongs to people** — store everything locally first, open formats (Markdown), no vendor lock-in, portable data - **DIY means freedom** — build with proven technology (SQLite, Git), keep the architecture clear, share knowledge freely - **Human-AI collaboration works** — each works in their preferred way, tools bridge the gap, learning is mutual - **Elegance through simplicity** — the best solutions are often the simplest I knew I wanted to maintain control, and lean towards the bootstrap method, rather than chase quick VC or angel funds. But I knew that way was going to be the slow, hard way. ### Aside: Licensing Another very real issue to reckon with was licensing. I had very adamantly decided to release Basic Memory under the AGPL 3.0 license. I'm a long time FOSS true believer, and it had always been a goal of mine to produce something I thought was worthwhile enough to share. But, I also wanted to make a business of this thing now. That's not impossible, many companies are built on FOSS, they just don't usually have the mega valuations and VC bucks. That does mean, however, to use the source code commercially, there are considerations. What I ended up doing, with advice from my lawyer, is licensing the Basic Memory to myself (via an LLC) with a proprietary license. This keeps the cloud IP clean, but still allows the commercial end to not worry about releasing code also. **NOTE**: It's actually a goal of mine to open source as much code as possible back into Basic Memory. But the fact is that's quite a bit of work to make it ready for other people's eyes. So in practice, it's easier to build the cloud infra in private, then move stuff over after its more stable. ### AI Memory is the TodoMVC of vibecoded apps I'll speak to the elephant in the room. AI memory apps are the vibe-coded equivalent of the web TodoMVC. Everybody tries it, and there are tons in every imaginable language and framework. Some even have good or novel ideas. Most are also free and open source. But the thing is, AI memory (or more generally context management for an LLM) is a very, very hard problem, once you get past the easy parts. On top of that, making an application (or service) that works across models, harnesses, platforms is a challenge. The type of challenge that is full of the non-fun problems to solve, platform issues, version incompatibilities, character encoding, file parsing, and synchronization. And all of that has to "just work", or your memory product is only good for you, not something lots of people will want to use. And further on top of that, the type of people that tend to want and build this product are usually trying to use some fancy tool. Use a graph db, put everything in a vector store, see how fast my retrieval score is? Look it passed this benchmark with better scores than everyone (sometimes hardcoding the results). And, at the end of the day, you still end up with another black box. Your AI can see your memory knowledge, but can you? If something is wrong, how do you know? What if you want to fix it, how easy is that? What if my AI keeps adding stuff to it and it just grows and grows, how well does it work? Solving all of these problems is much harder than vibe coding an app and calling it done. The hard problems are hard, even when the quick solution is easy. ### The grind Since starting writing most of this post, I have also re-implemented the web note editor for Basic Memory, added comments via [critic markup](https://fletcher.github.io/MultiMarkdown-6/syntax/critic.html){rel=""nofollow""}, threw out the y.js/hocus-pocus feature that allowed live collaborative editing, fixed how our mermaid svgs were rendering, and addressed some weird issue where CodeMirror would make frontmatter bold if it wasn't formatted properly. I think of this work as the *[necessary, but not sufficient](https://en.wikipedia.org/wiki/Necessity_and_sufficiency){rel=""nofollow""} work* of making a product. Its not what I wanted to deal with, but it was there in my way, so I had to fix it. This is what makes trying to put out a complete product so exhausting. But if you can't dogfood your own product, how can you expect others to use it? So that's life, I guess. ### Afterward It is a part of life, but the reality, is it wears you down. When I'm feeling burnt out from doing yet another arbitrary task, I start to think "why am I doing this, anyway?". For me it's personal, Basic Memory is my best idea for what to put out in the world right now. Its the thing I really care most about. So its a kind of big mix of a self-expression art piece (conception, design and execution is the act of creating art), combined with a science project (what happens if we mix these things together?), combined with a political statement (how I decide to present my work to be received - open source, user controlled data, no customer exploitation). It is through this process of self actualizing via creation that literally makes meaning by manifesting internal ideas externally. And that is an idea that keeps me motivated. I get really pumped thinking of all the cool stuff I want to do, and somehow, with help from a team of awesome folks, and a lot of AI assistance, it is seemingly possible. I appreciate all the users and feedback we have gotten so far, and the chance its given me to connect with new people, literally every day. And on top of that, seeing what people have built with Basic Memory that I didn't even think was possible has actually struck me with awe. When I started, Basic Memory seemed like such a small thing, and in the scope of "Big AI" and "Big Tech" it will always be. But to me its been just one small thing after another that keeps building into a bigger and bigger thing. ### Next up - The storage struggle - The unified tenant model - Making it fast - The circle closes: consolidation back into core # Basic Memory's take on the latest Claude news ## Claude’s new memory I’m sure most of our users have by noted the addition of Claude’s “search and reference chats” tool. It’s something we’ve been anticipating, of course, and it’s pretty much exactly what we expected. Like Chat’s “memory” (as discussed here {rel=""nofollow""} ), it’s a helpful addition…though not massively so yet. When one of our users asked Claude to contrast it with Basic Memory’s tools, it said “Chat search helps us reference what we discussed before. Basic Memory helps us understand the meaning and patterns from those discussions. Chat search is conversational context; Basic Memory is wisdom distillation.” “Wisdom distillation” feels a bit flowery for my taste. I read it more as “Claude search = recall, Basic Memory = meaning and pattern recognition.” Using it myself, I’ve found that it uncovers about 1/10th of the relevant material that Basic Memory does. But, hey, that’s better than nothing. Hopefully that will improve over time. If it does, great. But it’s still nowhere near what Basic Memory can do. One thing that Claude’s new built-in memory can’t do is function the way that Basic Memory can, as a prompt and persona manager and as a launching tool for pretty much any project. The built-in memory isn’t designed to hold knowledge, especially outside of the boundaries of the platform itself. It’s just designed to find conversations. And that distinction matters a lot, as anyone using Basic Memory can see. Interesting to note that last week Claude launched memory for teams for Teams and Enterprise subscribers {rel=""nofollow""}. That could definitely be pretty cool, and it’s a feature we’re excited to introduce ourselves. ## Claude’s increased integration with Microsoft products This news first arrived with Anthropic’s announcement ({rel=""nofollow""}) that Claude can now create Excel spreadsheets, PowerPoint presentations, Word docs, and PDF files that can be downloaded or saved to Google Drive. Seems like a pretty valuable and interesting turn, and one that moves us all one step closer to the dream of never cutting and pasting from AI to our final product ever again. And it appears it’s going to be a two-way street. Microsoft has announced that it’s going to increase AI capabilities in its Office 365 suite with the integration of Claude’s models. Which raises questions about the Microsoft/OpenAI relationship (Microsoft is OpenAI’s largest financial supporter with something like $13 billion invested in them so far), but some sites I’ve read suggest the shift indicates a move away from reliance on a single AI brand, and that seems right. One footnote that seems especially interesting is that Microsoft isn’t going to work with Anthropic directly but will instead access Claude via Amazon Web Services, despite AWS being a major cloud competitor. Which just shows how tangled and weird Big Cloud/AI alliances have become. ## Wild Claude backlash and Anthropic’s (sort of) confession If you pay attention to such things at all, you couldn’t help notice that the Anthropic and Claude subreddits have been absolutely flooded with endless complaints lately—mostly about a perceived degradation in service that seems to have driven many users to the brink of actual insanity. Even by the standards of subreddits that are constantly plagued by “That’s it, I’m cancelling” posts, the volume of these posts in the past couple of weeks has been so enormous as to be undeniable. Many of them claim they’re moving to Codex. Forgive me quoting a quoter, but TechCrunch cited a Reddit user who said exactly what I’ve thought at least a thousand times over the past few weeks, “Is it possible to switch to Codex without posting a topic on Reddit?” Our founder, Paul, has always argued that many of these outraged users are bots, and that position got some backing from on high this week when Sam Altman posted about the phenomenon. “I have the strangest experience reading this: I assume it’s all fake/bots, even though in this case I know codex growth is really strong and the trend here is real.” It’s hard to pin down exactly what’s going on. It definitely relates to the crest and crash of fandoms and the ways in which people seem to see themselves as “Claude people,” “ChatGPT people,” “Grok people” etc. The tribalism is real (and kind of scary). Whatever is happening, it appears the controversy wasn’t driven exclusively by bots, because Anthropic—cornered perhaps—released a statement saying that they’d received reports that Claude and Claude Code users were “experiencing inconsistent responses.” Ha! That’s one way of putting it. They claim one Sonnet 4 issue essentially spanned the entire month of August, was at its worst from August 29th to September 4th, and was then resolved. Not sure users agree, since plenty of the complaints were lodged after that date. They also note that “Importantly, we never intentionally degrade model quality as a result of demand or other factors.” Hmm. Could that really be the case? Hard to say, but I’m not sure I’m convinced. Whatever the truth, it highlights one of the reasons we built Basic Memory: your tools should be stable, model-agnostic, and under your control, not shifting beneath you without explanation. # Claude Remote: Run Commands on Your Machine from Claude.ai I've been using Claude Code daily for months now. It's become central to how I work—writing code, managing files, running builds. But there's a gap: when I'm away from my desk with just my phone, I lose all that capability. Claude.ai on mobile is great for conversation, but it can't touch my machine. Until now. ## Introducing Claude Remote [Claude Remote](https://github.com/basicmachines-co/claude-remote){rel=""nofollow""} is an open source MCP bridge that connects Claude.ai to your local machine. It lets Claude run shell commands, read and write files, and list directories—all from your phone or any web browser. The architecture is simple: ```text +----------------+ +-------------------+ +----------------+ | | SSE | | WS | | | Claude.ai |<-------->| Server (Cloud) |<-------->| Agent | | (iOS/Web) | MCP | | Relay | (Daemon) | +----------------+ +-------------------+ +----------------+ ``` 1. You chat with Claude on your phone or browser 2. Claude calls MCP tools (run\_shell\_command, read\_file, etc.) 3. The server relays commands to your connected agent via WebSocket 4. The agent executes commands and returns results 5. Results flow back through SSE to Claude ## Why Build This? The immediate motivation was practical: I wanted to check on long-running processes, read log files, or quickly edit configs without pulling out my laptop. But there's a deeper reason. MCP is becoming the standard for how AI interacts with external systems. Claude.ai already supports remote MCP connections—it just needs something to connect to. Claude Remote fills that gap with minimal complexity. ## Three Ways to Run It We've made deployment flexible based on your needs: **Local with ngrok** (simplest): Run everything on your machine with ngrok providing the HTTPS tunnel. No cloud deployment needed. Great for trying it out. **Docker + reverse proxy** (self-hosted): Run the server on your own infrastructure. You control everything. **Fly.io** (managed): Deploy to Fly.io for automatic HTTPS and global availability. A few commands and you're live. ## Security Considerations Running commands remotely requires care. Claude Remote includes several safety measures: - **Token-based authentication** between all components - **Path restrictions** limiting file access to home directory, `/tmp`, and `/var/tmp` - **All traffic encrypted** via HTTPS/WSS - **Command logging** to SQLite for audit trails This isn't a replacement for proper security practices, but it provides a reasonable baseline for personal use. ## Getting Started The quickest path to trying it out: ```bash # Clone the repo git clone https://github.com/basicmachines-co/claude-remote cd claude-remote # Generate auth token and start server export AUTH_TOKEN=$(openssl rand -hex 32) echo "AUTH_TOKEN=$AUTH_TOKEN" > .env docker-compose up -d # Start ngrok tunnel (in another terminal) ngrok http 8080 # Note your https://xxx.ngrok-free.app URL # Start the agent (in another terminal) cd agent uv venv && source .venv/bin/activate uv pip install -r requirements.txt export AUTH_TOKEN=$(cat ../.env | cut -d= -f2) export RELAY_URL=ws://localhost:8080/ws/agent python agent.py ``` Then add your ngrok URL to Claude.ai under Settings > Connectors > MCP, and you're connected. ## Open Source Claude Remote is released under AGPL-3.0, the same license we use for [Basic Memory](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""}. The code is straightforward Python—about 400 lines for the server, 400 for the agent. Fork it, modify it, make it yours. Check it out: [github.com/basicmachines-co/claude-remote](https://github.com/basicmachines-co/claude-remote){rel=""nofollow""} If you build something interesting with it, I'd love to hear about it. —Drew # Code Is Cheap Now. Context Isn't. *Simon Willison published something that crystallizes what everyone in agentic engineering is feeling but hasn't quite named yet.* --- Simon's guide, [Agentic Engineering Patterns](https://simonwillison.net/guides/agentic-engineering-patterns/code-is-cheap/){rel=""nofollow""}, opens with a deceptively simple observation: **writing code is cheap now.** Not *good* code — he's careful about that distinction. But the raw act of producing lines that compile and run? An agent can do that in minutes. The economics of software just shifted under our feet. Here's what caught our attention: > "Any time our instinct says 'don't build that, it's not worth the time' — fire off a prompt anyway, in an asynchronous agent session where the worst that can happen is you check ten minutes later and find that it wasn't worth the tokens." We do this literally every day. This morning, we spawned an agent to fix a PR while having a conversation about something else entirely. Ten minutes later, it pushed a fix. The old calculus — "is this worth a developer's afternoon?" — doesn't apply anymore. But here's what Simon identifies as still expensive: **good code.** Code that works, is tested, handles edge cases, is documented, and solves the right problem. His checklist is excellent. Go read it. We'd add one more item to that list: **code that has context.** ## The New Bottleneck When code was expensive, context was relatively cheap. A senior developer carries years of accumulated understanding — the codebase's quirks, the users' real needs, the decisions that shaped the architecture. That context lived in their head, and it was always available because *they* were the ones writing the code. Now the agent writes the code. But the agent wakes up fresh every session. It doesn't know why you chose Postgres over SQLite. It doesn't know that the CEO hates modals. It doesn't know that the last three times someone tried to refactor the auth module, it broke billing. **Code got cheap. Context became the bottleneck.** This is why "vibe coding" works for prototypes and breaks down for production systems. The vibes are the easy part — you describe what you want, the agent builds it. The hard part is everything the agent *doesn't know* that it needs to know. ## What This Means Simon's answer is to build new habits: better testing, better prompts, better review processes. He's right. But we think there's a deeper structural answer too. If code is cheap and context is expensive, then **the systems that capture, store, and deliver context to agents** become the most important infrastructure in software development. Not just "memory" in the chatbot sense — not "remember that I like dark mode." Real engineering context: design decisions, architecture rationale, user research, post-mortems, the accumulated understanding that makes a senior developer senior. The agent that can write code in ten minutes but has zero context will produce mediocre code. The agent that has deep, structured, searchable context about your project will produce code that *fits* — that solves the right problem in the right way for the right reasons. ## The Irony Here's the irony: most "AI memory" products store context in formats that only AI can read. Opaque vector stores, proprietary embeddings, cloud-only APIs. But context is most valuable when both humans and AI can read it. When a developer can open a file and see *why* a decision was made. When an agent can search a knowledge graph and find *what was tried before.* When the institutional knowledge isn't locked in anyone's head — or in anyone's proprietary cloud. Code is cheap now. Context isn't. And context should be something you can read. --- *We're [Basic Memory](https://basicmemory.com){rel=""nofollow""} — we build the knowledge layer that gives AI agents the context they need to write good code, not just fast code. Plain text. Human-readable. Yours to keep.* # The Conductor Model: What Programming With AI Actually Looks Like There's a bad metaphor floating around tech right now: that programming with AI is like having a junior developer. You give it tasks, review its work, and occasionally clean up its messes. That's wrong. It undersells both you and the AI. Here's a better one: **programming with AI is like conducting an orchestra.** ## The Conductor Isn't Hands-Off People who've never watched a conductor closely think the job is just waving a stick. Stand at the front, look important, take a bow. But a conductor is arguably the most expert person in the room. They know every instrument's part — the first violin, the oboe, the timpani — often better than the players themselves. They've studied the score for months. They hear when the cellos are a quarter-beat behind. They feel when the brass is overpowering the woodwinds. They just don't play any of the instruments. Sound familiar? ## You Still Have to Know the Score This is where the "AI replaces programmers" crowd gets it wrong. You can't conduct music you don't understand. A conductor who can't read a score isn't leading a performance — they're waving their arms while professionals do their jobs in spite of them. The same is true for coding with AI. If you don't understand what good architecture looks like, you'll accept bad architecture. If you can't recognize when two parts of a system are quietly working against each other, you won't catch it until something breaks in production. The AI will produce *something*, and you'll ship it, and it'll fall apart while you stand at the podium wondering what went wrong. **Domain expertise isn't optional. It's the whole job.** ## Real-Time Adjustment, Not Set-and-Forget A conductor doesn't hand out sheet music and leave. The performance is live. They're listening, watching, adjusting in real time: - *The tempo's dragging — push it.* - *The strings are too loud for this passage — pull back.* - *The flute entrance was late — cue it earlier next time.* This is exactly what effective AI-assisted development looks like. You're not writing a prompt and walking away. You're reading the output, catching the wrong note, redirecting before it cascades. ## Multiple Players, One Vision A symphony orchestra has 80+ musicians playing different parts simultaneously. The conductor is the only person who hears all of it at once and holds the vision of what it should sound like together. This is increasingly literal. Right now, people are running multiple AI agents working on different parts of the same codebase. Without someone holding the whole picture, you get noise. Parts that technically work but don't cohere. **The conductor's job is coherence.** ## What This Means for You Stop thinking of yourself as a manager delegating to a junior. That framing makes you passive. You're in the performance. You're leading it. Learn the score. Know every part. Listen for the wrong notes. Hold the vision. The best AI-assisted developers aren't the ones who write the cleverest prompts. They're the ones who understand their systems so deeply that they can hear when something's off — and correct it before it ships. # Dynamic Context Discovery: Why Smart AI Uses Less Context, Not More Here's a counterintuitive truth: as AI context windows grow larger, the smartest systems are getting better at using *less* context, not more. While models now support up to 1 million token context windows, Cursor just achieved a **46.9% token reduction** in their coding agents—and improved performance in the process. The secret? Dynamic Context Discovery, an approach that treats information like a lazy-loading system rather than dumping everything into the AI's attention span at once. This shift represents a fundamental change in how we think about AI context management, with profound implications for anyone building knowledge systems that work with AI. ## The Context Paradox Traditional AI systems suffer from what we might call "context obesity." They front-load massive amounts of information into every conversation, leading to: - **Token budget bloat** - paying for unused information in every API call - **Information overload** - critical details get buried in noise - **Reduced performance** - more context doesn't always mean better results - **Higher costs** - every unused token still costs money The assumption was simple: bigger context windows mean better AI. But recent research reveals the opposite. **Context engineering**—the art and science of curating what goes into the limited context window—often matters more than raw capacity. ## How Dynamic Context Discovery Works Instead of including everything upfront, dynamic context discovery treats information as discoverable resources that only consume tokens when actually accessed. Think of it as "lazy loading" for AI context. Cursor's implementation reveals five key techniques: **Converting Tool Outputs to Files**: Rather than injecting large data directly into prompts, write information to files and give agents tools to selectively read what they need. Files enable lazy loading—information exists and is discoverable, but doesn't consume tokens until accessed. **Chat History as Files**: Previous conversations get stored as files rather than included in every new context window. **Selective Tool Loading**: Instead of loading full descriptions for dozens of tools upfront, agents initially receive only tool names, then look up full descriptions only when needed. This single change drove that 46.9% token reduction. **Agent Skills on Demand**: Supporting structured skills that can be loaded when relevant, not loaded by default. **Terminal Sessions as Files**: Treating long-running outputs as files rather than inline context. ## Beyond Token Savings: Better Results The surprising discovery isn't just efficiency—it's that **less context often produces better results**. Windsurf found that combining multiple retrieval techniques (embedding search, grep, knowledge graphs, AST parsing) achieved **3x better retrieval accuracy** than single methods. But the key insight was selectivity: only retrieve what's relevant for the current task. JetBrains Research discovered that simple observation masking (hiding irrelevant previous outputs) wasn't just 52% cheaper—it boosted solve rates by 2.6% compared to unmanaged context. Sometimes the simplest approach beats sophisticated AI-powered summarization. ## The Knowledge Management Connection This research validates something we've believed at Basic Memory: the future of AI-human collaboration isn't about feeding AI everything you know. It's about creating systems where AI can intelligently discover what it needs from your knowledge when it needs it. Consider how this maps to personal knowledge management: **Files as First-Class Context**: When your knowledge lives in readable files (like Markdown), AI can selectively retrieve relevant information rather than processing your entire knowledge base every time. Your notes become lazy-loadable context. **Semantic Connections Over Brute Force**: Instead of dumping everything into context, smart systems help AI find relevant connections between your ideas. The goal is intelligent retrieval, not information overload. **Local-First Advantages**: Research shows that local caching provides **10x cost reduction** when properly implemented. When your knowledge lives locally, AI can access it efficiently without API costs for storage, and you maintain complete control over what gets shared. ## What This Means for Your Workflow The implications extend far beyond coding agents. If you're using AI for research, writing, or knowledge work, dynamic context discovery principles can transform your workflow: **Start with Structure**: Organize your knowledge in discoverable files rather than monolithic documents. Break large topics into focused, interconnected pieces. **Make Context Explicit**: Instead of hoping AI remembers everything from a long conversation, create reference documents it can selectively access. Your meeting notes, project requirements, and research findings become retrievable resources. **Think Connections, Not Collections**: Focus on how your ideas connect rather than just accumulating information. Semantic relationships help AI find relevant context without processing everything. **Embrace Transparency**: Use systems where you can see what context AI is accessing. Black-box vector databases make it impossible to understand or debug AI's knowledge retrieval. ## The Bigger Picture Dynamic Context Discovery represents a maturation in AI system design. We're moving from "feed the AI everything" to "help the AI find what it needs." This shift mirrors broader trends in software engineering—from monolithic applications to microservices, from loading everything upfront to just-in-time resource allocation. For knowledge workers, this means the tools that will thrive are those that make your knowledge discoverable and selectively accessible, not those that try to cram everything into every conversation. The future isn't bigger context windows. It's smarter context discovery. Your knowledge deserves a system that works as intelligently as you do—one that helps AI find the right information at the right time, without overwhelming either of you in the process. Download Basic Memory for free at [GitHub](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} or try Basic Memory Cloud free for 7 days at [basicmemory.com](https://app.basicmemory.com/auth/signup){rel=""nofollow""}. --- **Further Reading**: [Dynamic Context Discovery for Production Coding Agents](https://cursor.com/blog/dynamic-context-discovery){rel=""nofollow""} - Cursor's original blog post by Jediah Katz # Enhancing LLM Conversations with Persistent Knowledge LLMs are amazing tools. As soon as I started "just talking to them" like I was having a real conversation, their capabilities really opened up. But, one thing was always a pain. Every conversation was starting over at the beginning. You have a great conversation about your project one day, and the next day - nothing. It's gone. You have to explain everything all over again. This limitation was driving me crazy. AI conversations are productive in the moment, but the knowledge vanishes when the chat ends. It's like working with someone who has perfect general knowledge but forgets everything about your specific situation each time you talk. ## The Problem with Forgetting I've seen this play out over and over: 1. You have a detailed conversation with an AI about your research project 2. You get valuable insights and make progress together 3. You come back the next day to continue 4. The AI has no memory of what you discussed This pattern makes it nearly impossible to build on previous context. You end up repeating yourself, manually copying information from old conversations, or trying to remember where that one key insight is buried in your chat history. In my own work, I found myself copying snippets from previous conversations just to maintain continuity. I knew there had to be a better way. ## Building a Memory Layer Basic Memory started as a simple idea around Christmas 2024: what if conversations with AI could build lasting knowledge structures instead of disappearing? We designed a system where: 1. Key information from conversations gets captured in a knowledge graph 2. This graph maintains connections between related topics 3. When you start a new conversation, the AI can navigate this graph to find relevant context The result? AIs that remember what you've discussed before and build on that knowledge over time. ## How It Actually Works Let me walk through a concrete example. During a conversation about coffee brewing, I mentioned Ethiopian beans. The system created a structured note containing: ```text # Ethiopian Coffee Beans ## Observations - [origin] Grown primarily in Yirgacheffe, Sidamo, and Harrar regions - [flavor] Known for bright acidity and floral, fruity notes - [processing] Natural processing common, contributing to berry flavors ## Relations - pairs_well_with [[Pour Over Brewing]] - contrasts_with [[Dark Roast Methods]] ``` A week later, when discussing brewing methods, the AI was able to suggest pour over specifically for my Ethiopian beans, referencing their floral characteristics from our previous conversation. It wasn't starting from scratch - it had access to context from across our conversation history. ## The Real-World Difference Using this system has changed how I work with AI in several ways: 1. **Conversations build on each other**: Each interaction contributes to a growing knowledge base 2. **Context flows naturally**: The AI can find relevant information without me explicitly providing it 3. **Ownership of insights**: Everything is captured in a format I control, not lost in cloud services 4. **More productive interactions**: Less time spent re-explaining, more time making progress The shift from ephemeral to persistent conversations makes AI feel more like a continuous collaborator than a stateless tool. ## What's Next This is still early work. There are challenges in determining what information should be captured, how to navigate large knowledge graphs efficiently, and how to handle conflicting or outdated information. But the core concept - that AI conversations should contribute to durable knowledge rather than disappear - has proven incredibly valuable. At Basic Machines, we're continuing to refine how information flows between humans and AI systems, always with the principle that your knowledge should remain in your control. If you've experienced the frustration of AIs that forget everything you teach them, I'd love to hear your thoughts on how we might build better systems for knowledge continuity. # Everyone's Building Memory. Nobody's Building Yours. A startup founder woke up last week and watched their close rate drop from 70% to 20% overnight. Claude shipped a feature. Their startup *was* the feature. This keeps happening. ChatGPT added memory. Claude added memory. Manus added memory. Every AI company is racing to bolt on some version of "I remember you" — a black box that stores things about you somewhere, managed by someone else, invisible to you. And every few months, a VC-funded startup discovers that the platform they built on top of just absorbed them whole. We've watched this cycle play out in our own space. We build [Basic Memory](https://basicmemory.com){rel=""nofollow""} — local-first, plain-text knowledge tools for humans working with AI. And the "memory" space has gotten *very* crowded: - Mem0 raised $24M to build an opaque memory API - Zep abandoned their open source users and went enterprise-only - Supermemory raised $3M to inject memory into every prompt - A new "AI memory" repo hits GitHub trending every week, built by someone vibe-coding over a weekend Every single one of them is building memory as a feature. A thing the AI has. A thing the platform controls. We're building something different: memory as *yours*. ## What "yours" actually means When we say your memory is yours, we mean it literally: - It's **plain text files** in your knowledge base. Markdown you can open in any editor. - You can **read every word** the AI remembers about you. Edit it. Delete it. - You can **take it with you** — to another AI, another tool, another decade. - The AI and the human **read and write the same files**. No translation layer. No API. No lock-in. Nobody else does this. Not because it's technically hard, but because it's a different philosophy. Opaque memory is easier to ship, easier to monetize, easier to control. Transparent memory requires trusting your users. We trust our users. ## Why platform memory can't replace this Here's the thing about that startup that lost 70% of their close rate overnight: they were selling something Claude could replicate as a checkbox feature. The moment the platform decided "we do this now," the startup's value proposition evaporated. We don't have that problem. Not because we're smarter or faster. Because we're playing a different game. Claude's memory is Claude's memory. It lives inside Anthropic's infrastructure, formatted however they want, accessible only through their interface. If you switch to a different model tomorrow, that memory stays behind. If Claude changes how memory works, you adapt or lose it. Basic Memory is *your* memory. It lives in files you control, in a format that will outlast every AI company currently in existence. Plain text has been around for fifty years. It'll be around for fifty more. Claude shipping memory doesn't threaten us any more than Google Docs shipping spell check threatens Merriam-Webster. We're not in the feature business. We're in the ownership business. ## Bootstrapped changes everything We're bootstrapped. We're profitable. We're growing. That changes everything about how you think about competition. When you've raised $24M, you *need* to be bigger than the platform. You need hockey-stick growth, market dominance, a moat that keeps the giants out. And then one day the giant steps over your moat like it isn't there, and you're left explaining to your investors what happened. When you're bootstrapped and profitable, the only competition you have is yourself. Can we make the product better this week than it was last week? Can we serve our users more honestly? Can we build something that lasts? That's not a moat. Moats are defensive. What we have is a mission: your knowledge should belong to you. Full stop. Missions don't get killed by feature launches. ## The community gets it The people using Basic Memory understand what's different. They're not using it because it has the best marketing or the biggest funding round. They're using it because it works in a way nothing else does. *"My startup would not be where we are right now without Basic Memory."* That's not someone impressed by a feature. That's someone who found a tool that respects how they think and work. That's the difference between building *for* users and building *at* them. ## The real question Every time a platform ships "memory," ask yourself: whose memory is it? Can you read it? Can you edit it? Can you take it somewhere else? Can you hand it to a different AI and have it just work? Will it still be accessible in five years? If the answer to any of those is no, it's not your memory. It's theirs. You're just renting it. We think you deserve better than that. And we're going to keep building it, one plain-text file at a time — whether Claude ships memory or not. --- *Basic Memory is open source and built for humans who want to own their knowledge. [Try it →](https://app.basicmemory.com/auth/signup){rel=""nofollow""}* # When Dependencies Break at 9pm: A FastMCP Story *July 2, 2025* Last night at 9pm CT, a user reported that they couldn't connect their MCP server to Claude Desktop. The error logs showed "Unexpected token '╭'" and a cascade of "... is not valid JSON" errors. Within minutes, we discovered this wasn't just affecting one MCP server - both of our open source MCP servers (Basic Memory and open-ghl-mcp) were experiencing the same issue. ## The Timeline **9:01 PM CT** - First user report comes in via Discord. They were trying to connect an MCP server and getting JSON parsing errors. **9:08 PM CT** - I checked our own projects. Both `open-ghl-mcp` and Basic Memory were showing identical symptoms. The MCP servers were starting but immediately failing with JSON parsing errors. **9:15 PM CT** - Dove into the logs. Found something unusual - decorative ASCII box drawing characters (`╭`, `│`, `╰`) appearing in what should be pure JSON output. **9:22 PM CT** - Traced the issue to FastMCP v2.10.0, released earlier that day. The new version was outputting decorative borders to stdout, breaking the JSON-based MCP protocol. **9:45 PM CT** - Filed [issue #1010](https://github.com/jlowin/fastmcp/issues/1010){rel=""nofollow""} with FastMCP to alert the community. **10:30 PM CT** - Pushed [PR #203](https://github.com/basicmachines-co/basic-memory/pull/203){rel=""nofollow""} pinning FastMCP to versions below 2.10.0. **10:55 PM CT** - Released Basic Memory v0.14.1 with the fix. ## The Technical Details The Model Context Protocol (MCP) relies on clean JSON communication between servers and clients. When FastMCP v2.10.0 added decorative ASCII box drawing to stdout, it broke this contract: ```text ╭─────────────────────────────────────────╮ │ FastMCP Server Starting... │ ╰─────────────────────────────────────────╯ {"jsonrpc": "2.0", "method": "initialize"} ``` Clients like Claude Desktop saw those box drawing characters and threw JSON parsing errors. The result? Complete failure of MCP server functionality. ## The Fix The immediate fix was straightforward - pin FastMCP to a working version: ```python # In pyproject.toml dependencies = [ "fastmcp>=2.3.4,<2.10.0", # Constrained to prevent breaking change # ... other dependencies ] ``` ## Lessons Learned 1. **Dependencies can break at any time** - Even well-maintained projects can introduce breaking changes. Having monitoring and rapid response procedures is crucial. 2. **Community matters** - Within 2 hours, we had identified the issue, created a fix, filed an upstream bug report, and released a patch. This was only possible because users reported the issue quickly and clearly. 3. **Pin strategically** - While we generally prefer flexible version constraints, critical infrastructure dependencies sometimes need upper bounds to prevent breaking changes. 4. **Unit testing is important** – When a lot of people depend on your code, don't rush. Unit tests are essential, but thoughtful, careful releases matter even more. Take your time and get it right. ## Moving Forward We've added explicit version constraints for FastMCP until the upstream issue is resolved. The FastMCP team is aware of the issue, and we expect they'll address it soon. For Basic Memory users, simply upgrade to v0.14.1: ```bash # Using uv (recommended) uv tool upgrade basic-memory # Using pip pip install --upgrade basic-memory # Using Homebrew brew upgrade basic-memory ``` ## Thank You Special thanks to the user who provided the quick and detailed bug report. This is what makes open source amazing - users who care enough to report issues clearly, maintainers who jump on fixes immediately, and a community that works together to keep things running. If you encounter issues with Basic Memory or any of our tools, please don't hesitate to reach out. You can find us at [@basicmachines-co](https://github.com/basicmachines-co){rel=""nofollow""} on GitHub, and file issues directly on the [Basic Memory repository](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""}. ## Follow Up ## FastMCP reverted the change in a [hot fix](https://github.com/jlowin/fastmcp/releases/tag/v2.10.1){rel=""nofollow""} very quickly also. Sometimes clever ideas have unintended consequences. *Basic Memory is local-first knowledge management for AI. It lets you build a personal knowledge graph that AI assistants can navigate, search, and extend. [Learn more →](https://basicmemory.com){rel=""nofollow""}* # Google's New Open Knowledge Format Is Basically Basic Memory's Thesis Google just formalized an idea Basic Memory has been built around from the beginning: useful AI context should live in plain files that people and agents can both read. On June 12, [Google Cloud announced the Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/){rel=""nofollow""}, or OKF. It is an [open specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md){rel=""nofollow""} for representing organizational knowledge as a directory of Markdown files with YAML frontmatter and links. What's nice about it is that the goal is not some proprietary catalog or another vendor-owned memory silo. It is a portable shape for context: something humans can edit, agents can consume, and tools can move between. It would be flattering to imagine Google arrived here because they noticed that Basic Memory has been doing the same thing since the introduction of MCPs. But the more interesting version is probably that the shape of AI memory is simply becoming obvious to everyone in the game. AI agents need context, and context has to live somewhere. If it only lives inside one product, one vendor database, or one API, it is fragile. If it lives in ordinary files, people can read it, edit it, sync it, version it, move it, and keep it. Google puts the point plainly: > "The answer to this problem isn't another knowledge service. You need a format." **Exactly.** That is what makes OKF noteworthy. It gives organizational knowledge a simple, portable form: **Markdown, frontmatter, links, folders.** An OKF bundle is a directory of Markdown files. Each file represents a concept: a dataset, a metric, an API, a decision, a process, or whatever else an agent might need to understand. Files can link to other files. `index.md` can help agents navigate. `log.md` can record history. That is basically it. And that is why it is interesting. The old way of thinking about AI knowledge was: put everything into a system, then ask the system to be smart about it. OKF points toward a better pattern: keep the knowledge in a form humans and tools both understand, then let many systems use it. Markdown. Frontmatter. Links. Files. It is boring in the best possible sense. Like Git is boring. Like SQLite is boring. Like Markdown is boring. The kind of boring that outlives flashier approaches. It also lines up closely with Basic Memory. Same premise: memory shouldn't disappear into someone else's black box. It should live in ordinary Markdown files you control, readable by humans, writable by agents, synced when you want it, yours either way. OKF gives that premise a name. But a frame isn't a memory system. A folder of Markdown files is a good start. Portable. Inspectable. Git-friendly. Already better than most AI memory products. But once an agent actually has to use that folder, the questions start fast. How does it search across files? Follow the graph? Know what changed? Let a human and an agent edit the same knowledge without losing the structure? Show up in Claude, ChatGPT, Gemini, Cursor, Obsidian, everywhere you actually work? **That's the part Basic Memory handles.** OKF is everyone agreeing to write knowledge on index cards instead of locking it in a filing cabinet. Basic Memory is the card catalog, the cross-references, the librarian, the circulation desk, everything that makes the cards useful every day. So: did Basic Memory just become philosophically aligned with Google? Kind of. Mostly, Google just put a name on a pattern we've been building toward all along. Either way — the future of AI memory isn't a black box. It's files: yours, readable, and useful everywhere you go. # Semantic Search in Basic Memory You wrote a note three weeks ago about "hardening the authentication system." Today you search for "login security improvements." No results. The words are different. The meaning is the same. That's the problem with traditional search. It aims to match words, not concepts. If you don't remember exactly how you phrased something, you might never find it again. As of v0.19.0, Basic Memory works differently. It understands meaning. Search for "login security improvements" and it finds your note about authentication hardening, because it knows those two things are about the same idea. It's the difference between a filing cabinet and a librarian. A filing cabinet only gives you what you put in the right folder. A librarian listens to what you're looking for and finds it. ## How to Think About It When you save a note, Basic Memory does two things: it indexes the words (like traditional search always has), and it also encodes the meaning of the text. When you search, both of those indexes get checked. If something matches on words and meaning, it rises to the top. If it only matches on meaning (like your auth hardening note showing up for a login security query) it still comes back. ## What This Looks Like in Practice - *"ways to make the frontend faster"* finds notes about React performance, bundle size, lazy loading — even if none of them use the word "faster" - *"what we decided about the database"* finds notes about your Postgres vs SQLite evaluation, schema decisions, migration planning - *"that conversation about pricing"* finds notes about pricing strategy, customer feedback on tiers, competitive analysis You just search the way you think. [Semantic search docs →](https://docs.basicmemory.com/concepts/semantic-search){rel=""nofollow""} [v0.19.0 release →](https://basicmemory.com/blog/basic-memory-v0-19-0-release) # Why Local-First Knowledge Management Matters "Where's your data right now?" It's a simple question, but most people can't answer it confidently anymore. Your notes, documents, messages, and thoughts increasingly live on someone else's computers. I find that troubling. At Basic Machines, we built Basic Memory with a core principle: your knowledge should live on your computer, in formats you control, for as long as you want to keep it. ## The Problem with Today's Knowledge Tools Most modern knowledge tools are cloud-first by design. Whether it's note-taking apps, task managers, or AI assistants, they typically store your data on remote servers. This approach has real consequences: - Your access to your own knowledge depends on someone else's servers staying online - Companies can change terms, increase prices, or pivot their business models - Services shut down, sometimes with inadequate export options - Your personal knowledge becomes vulnerable to data breaches - You need an internet connection to access your own thoughts These aren't just theoretical concerns. We've all seen previously reliable services disappear, taking user data with them or making it difficult to extract. ## Files as the Source of Truth The core insight that sparked Basic Memory was simple but powerful: what if your knowledge lived in files you control, while still maintaining the rich structure needed for sophisticated tools? This "files as source of truth" approach means: - Your knowledge lives in standard Markdown files on your computer - You can edit these files with any text editor or Markdown tool - The files remain accessible even if our software disappeared - You control how they're backed up, synced, or shared Behind the scenes, we maintain a knowledge graph that enables powerful features, but the files always remain the authoritative source. If there's ever any conflict, the files win. As the earliest design document for Basic Memory stated: > "At the heart of Basic Memory is a simple but powerful idea: your knowledge should live in files you can see, edit, > and control. Two-way sync makes this possible by keeping your knowledge graph and your markdown files in perfect > harmony." ## Real Benefits in Practice Using this system has changed my relationship with knowledge tools: - I'm more willing to invest in building structured notes, knowing they'll remain accessible - My notes work with multiple tools - I can use Obsidian today, something else tomorrow - I have genuine peace of mind knowing my knowledge base isn't tied to any company's future - I can work offline without limitations - I can sync changes back to LLM context any time Perhaps most importantly, this approach supports genuine ownership. These aren't just data exports or backups - they're the primary storage format. Your knowledge lives in your files, not our database. ## Where We're Headed Building true local-first software isn't easy. Synchronization is challenging. Collaborative features require careful design. Performance at scale demands thoughtful optimization. But we believe these challenges are worth solving. The pendulum has swung too far toward centralized, cloud-first knowledge systems, and it's time to restore balance. At Basic Machines, we're committed to the idea that the most personal data - your thoughts, notes, and knowledge structures - should remain under your control by default. If you're interested in tools that respect your ownership while providing powerful features, I'd love to hear your thoughts on where local-first knowledge management should go next. # Basic Memory now supports import + local sync We’ve just rolled out two big updates to Basic Memory that change how you can work with your AI knowledge for good. For those new here, Basic Memory is a tool that helps your AI actually remember what matters. It turns your conversations, prompts, and notes into a connected, searchable web that you and your AI can both read, edit, and develop. Until now, Basic Memory worked beautifully for new projects. But a lot of users already had tons of knowledge living in their ChatGPT and Claude histories and they wanted an easy way to import it. Others wanted a way to tie our cloud project into their favorite Markdown tools like Obsidian or VS Code. So, we fixed that. ## 1. One-step import Now you can upload your entire chat history from ChatGPT or Claude, JSON files and all. Basic Memory turns every conversation into linked, searchable notes inside your workspace. No cold starts. No re-prompting. No copy/paste back and forth. Your past work instantly becomes living context you can build upon. You can search it, connect it, or even ask your AI questions like: > “Summarize my conversations about product design and show what ideas came up most often.” ## 2. Local sync (for Markdown nerds like us) This one’s for the people who love to see their files. Basic Memory can now sync bi-directionally with any local Markdown folder: Obsidian, VS Code, or whatever you prefer. Edit a note locally, it appears in your Basic Memory workspace. Edit online, it syncs back down. Your ideas stay portable, visible, and 100% yours. Now you can now start with your existing ideas. And keep your data close at hand. And you can build something durable: a memory that’s as open and flexible as Markdown itself. If you haven’t tried Basic Memory in a while, this is the time. Just you, your AI, and a smarter way to work. basicmemory.com We’re excited to see what you do with it. # Markdown First: Replace Your Code I've been writing specs instead of code for most of my work lately. A markdown file describing what I want, fed to Claude Code, produces working implementations in minutes. When something breaks, I fix the spec and regenerate. **The code is disposable. The spec is the product.** [Sean Grove](https://x.com/sgrove){rel=""nofollow""} from OpenAI put it well at the [AI Engineer World's Fair](https://www.ai.engineer/worldsfair){rel=""nofollow""}: > Treating prompts as disposable while carefully version-controlling generated code is like shredding the source and then very carefully version controlling the binary. I've been writing specs over code for a few months now and it's working exceedingly well with my agent swarms. ## The spec is the source code AI coding tools got good enough this past year that writing code is no longer the bottleneck. Claude Code, Cursor, Copilot, Windsurf, Gemini CLI all translate intent into working implementations. **The scarce resource now is clear thinking expressed in plain language.** [Guy Podjarny](https://www.linkedin.com/in/guypo/){rel=""nofollow""} from [Tessl](https://www.tessl.io/){rel=""nofollow""} lays out three stages of adoption. Stage one is **spec-assisted**: you give the AI structured context like coding standards and architecture docs, and unlike a human developer who skims the README, the AI actually reads every word. Stage two is **spec-driven**: you modify the spec first, then apply the change to code. Stage three is **spec-centric**: comprehensive specs and tests make code fully disposable. You regenerate implementations without carrying forward technical debt. Most teams I talk to are somewhere between stage one and two but the trajectory is clear. ## What it looks like in practice [Alex Op](https://x.com/alexanderop_dev){rel=""nofollow""} documented a spec-driven workflow with Claude Code that migrated a storage layer from SQLite to IndexedDB. Fifteen files, 14 atomic commits, about 45 minutes. The AI researched the problem in parallel, consolidated findings into a spec, asked clarifying questions, then delegated individual tasks to subagents that each produced one commit. **The part that sold me: the spec survives session restarts and context window limits.** When things go sideways, you open a new chat with the pinned spec and pick up where you left off. No re-explaining. We've lived this building Basic Memory. Context evaporation is the core problem we set out to solve, and a well-written spec in markdown is immune to it. ## Good specs leave room A good spec doesn't need to specify every detail. It defines what matters -- business rules, constraints, success criteria -- and lets the AI figure out the how. Podjarny calls the incompleteness a feature. **The same spec can produce different implementations for different contexts.** Writing good specs is harder than it sounds. You're communicating intent and constraints to an intelligent system that makes implementation decisions on your behalf. You have to think through edge cases, constraints, and failure modes before a single line of code exists. The better your spec, the better those decisions. ## The tooling already exists Multiple open-source frameworks support this today. [Claude-code-spec-workflow](https://github.com/Pimzino/claude-code-spec-workflow){rel=""nofollow""} walks you from requirements through tasks to implementation. [CC-SDD](https://github.com/gotalab/cc-sdd){rel=""nofollow""} brings structured requirements to Claude Code. [OpenSpec](https://github.com/Fission-AI/OpenSpec){rel=""nofollow""} provides general-purpose spec-driven development for any AI coding assistant. [AGENTS.md](https://agents.md/){rel=""nofollow""} is becoming a standard for putting project rules in one place any AI agent can consume. Pre-commit hooks validate generated code against specs. AI spawns subagents that each handle one atomic piece. The whole thing runs on markdown files in version control, reviewed in PRs, iterated on collaboratively. Podjarny forecasts that by end of 2027, developers using AI agents will rarely examine generated code directly. Think about how rarely you look at compiled bytecode today. The abstraction layer just moves up. ## Your specs need memory All of this works well inside a single project and a single session. But real work spans projects, sessions, and tools. Your architectural decisions from three months ago should inform the spec you're writing today. The debugging pattern you discovered last week should be available when you hit something similar next month. I've been keeping my specs, architectural decision records, and project rules in Basic Memory for months. The first draft of this blog article was written with a spec. When I start a new Claude Code session, **the AI builds context from everything I've written**, follows connections between related decisions, and produces specs consistent with past work. No re-explaining the architecture. No contradicting last month's decisions because the AI forgot about them. The markdown file is the product. Everything else is generated. Try it for a week. Write a spec, hand it to your AI tool of choice, and see what comes back. Fix the spec instead of the code. You probably won't go back. We're building AI memory for humans. Basic Memory keeps your specs, decisions, and context in plain markdown you own, connected through a semantic knowledge graph that any AI tool can read. [Basic Memory Cloud](https://app.basicmemory.com/auth/signup){rel=""nofollow""} is the best way to connect your context to your own thoughts. *-- Drew Cain, [Basic Memory](https://basicmemory.com/pricing){rel=""nofollow""}* --- **Further Reading:** - [Basic Memory Cloud - Try it free](https://app.basicmemory.com/auth/signup){rel=""nofollow""} - [OpenClaw Built Its Own Basic Memory Plugin](https://basicmemory.com/blog/basic-memory-for-open-claw) - [Semantic search PR - spec driven development](https://github.com/basicmachines-co/basic-memory/pull/550){rel=""nofollow""} - [Basic Memory Documentation](https://docs.basicmemory.com){rel=""nofollow""} # How MSPs Can Give Clients a Shareable Private AI Knowledge Base *Your clients are adopting AI whether you're in the loop or not. You either own that layer or watch it happen around you.* Every MSP is running into the same thing right now. Your clients' staff have discovered AI, and they're using it…badly. They're pasting company data into whatever chatbot is open in another tab, getting answers that are confidently wrong because the model has never seen their environment. Some are on Claude, others on Chat, one dude is apparently using a local model you've never heard of that his nephew installed for him. Everyone's getting different answers because everyone is only telling their AI what they can remember in the moment or what they happen to have access to. They all know they're supposed to be using AI, but no one knows exactly how. But the biggest problem is that data is going somewhere you don't control and churning out answers nobody's accountable for. Which raises an interesting issue. The thing that makes AI actually useful to a business is memory of that business. And that memory is exactly the layer you, the MSP, are positioned to own. ## Where does the knowledge live? Think about what you already maintain for every client: the network layout, the app inventory, the weird one-off fix from eighteen months ago, who's allowed to approve what. Some of it lives in a documentation tool. Most of it lives in your senior techs' heads. But the pain points are inevitable. First, the documentation drifts. You write it once, the environment changes the next week, and now it's only sort of trustworthy. Second, general-purpose AI is useless on it. When you drop ChatGPT into a client ticket and it has no idea what their setup is, your techs still do all the work by hand. The fix is simple: give the AI a persistent, editable memory for each client, one that stays current because it updates automatically as you work. ## What a per-client AI knowledge base actually is With Basic Memory, you stand up a private, isolated knowledge base for each client. Your techs' AI tools (Claude, ChatGPT, Cursor, whatever they already use) read from it and write to it. Onboard a new device and the inventory updates itself. Resolve a novel issue and the fix is captured where the next tech (or the next AI) will find it. Ask "what's this client's backup setup?" and you get the actual answer. Because it's all plain Markdown under the hood, nothing is locked in a proprietary format, and each client's data stays physically separated from every other client's. It's one clean, isolated workspace per customer. ## What it looks like in a real shop We don't have to describe this hypothetically. Basic Memory user Cody runs his entire MSP on Basic Memory. In a video walkthrough, he onboards a client's new hire (laptop assigned, inventory updated, warranty logged) from a single instruction, then spins up a live inventory dashboard built straight from those same notes. It's the clearest picture we've got of what "a knowledge base that runs the business" actually means day to day. Watch [Cody's walkthrough on YouTube](https://www.youtube.com/watch?v=IgZqDfMtxPk){rel=""nofollow""}, or read the [full case study](https://basicmemory.com/case-studies/luminary-solutions) for how he got there. ## Two ways to run it If you just need SSO and audit for your own team, you don't need anything special. The [Business plan](https://basicmemory.com/pricing) ($30/seat/month) gives any company single sign-on (SSO/SAML), audit logs, admin and security controls, HIPAA-compliant hosting, and priority support. It's billed to you directly. This is the direct route that's open to everyone. If you're deploying Basic Memory for other companies, running IT or AI for a book of clients, that's the [Partner program](https://basicmemory.com/partners). You get a single portal to manage every client workspace, SSO that works with whatever identity provider each client already uses (Google, Microsoft Entra, and more), and one consolidated invoice broken out per customer so you can rebill at your own margin. And because you're bringing us your clients, we'll work out a special partner deal with you rather than charging you list. The short version: Business is the plan anyone can buy. The Partner program is for the MSPs and consultancies who want to make it a line of business. ## Getting started If you want to see the shape of it first, [Cody's walkthrough](https://basicmemory.com/case-studies/luminary-solutions) is the fastest way. If you're ready to run a client on it, the [Business plan](https://basicmemory.com/pricing) has a 7-day trial and you can be live today. And if you're an MSP or AI consultancy thinking about doing this across your whole client base, [come talk to us about the Partner program](https://basicmemory.com/partners). Seriously, reach out to us. We're responsive, serious about building a great product, and we have the resources to get your systems set up just the way you want them. Your clients are going to build their AI memory somewhere. It might as well be with the provider who already knows their environment better than anyone: you. # Giving Your AI Agent a Memory That Actually Works Most AI assistants wake up every morning with amnesia. You explain your project. Again. You remind them about that decision you made last week. Again. You re-establish context that took three conversations to build. Again. We built a plugin that fixes this for OpenClaw agents. Two commands, zero configuration, and your agent remembers everything — across sessions, across days, across context window resets. ```bash openclaw plugins install @basicmemory/openclaw-basic-memory openclaw gateway restart ``` That's the whole setup. ## What Your Agent Gets **Composited memory search.** When your agent searches its memory, the plugin queries three sources in parallel: your MEMORY.md file, the full knowledge graph, and any active tasks. One search, three data sources, merged results. The agent doesn't need to know where something is stored — it just finds it. **Auto-capture.** Every conversation turn gets recorded as a timestamped entry in a daily note. You're not maintaining a journal — it happens in the background. Weeks later, when you need to know "what did we decide about the database migration?", it's there. **Auto-recall.** Session starts, the agent immediately loads active tasks and recent notes. No "let me catch you up" ritual. No "read my files first" prompt engineering. It just knows what it was working on. **14 tools, 7 slash commands, 6 skills.** The full Basic Memory toolset — search, read, write, edit, schema validation, project management. Plus shortcuts like `/remember` (save something), `/recall` (find something), and `/reflect` (review and consolidate). ## Why This Isn't Just Another Memory Plugin Here's what's different: everything your agent remembers is stored as plain markdown files that you can open and read. Not embeddings in a vector database you can't inspect. Not JSON blobs in a cloud API you don't control. Markdown files. In a folder. On your machine. Your agent writes a note about a meeting? Open it in VS Code. See exactly what it captured. Fix the part it got wrong. Add the context it missed. Save the file — your agent sees the change instantly. This is what "bidirectional" means in practice. The AI writes things down. You read them. You correct them. The AI reads your corrections. The knowledge base gets better because both sides are working with the same transparent format. It's the difference between an AI that claims to remember and an AI whose memory you can verify. ## Multi-Project Access Because the plugin connects to the full Basic Memory stack, your agent isn't limited to a single workspace. It can search across every project in your knowledge base — personal notes, work projects, research, whatever you've organized. Some projects stay local. Some route through Basic Memory Cloud for cross-device access. The agent uses the same tools either way. You decide what lives where. ## The Skills The plugin bundles six pre-built skills that teach your agent best practices: - **memory-notes** — How to write well-structured notes with proper frontmatter, observations, and relations - **memory-tasks** — Structured task tracking that survives when the context window resets - **memory-schema** — Keeping note structures consistent as your knowledge base grows - **memory-reflect** — Reviewing recent work and consolidating insights (inspired by how humans review journals) - **memory-defrag** — Splitting bloated files, merging duplicates, pruning stale info - **memory-metadata-search** — Finding notes by status, priority, or any custom field These aren't documentation. They're instructions your agent reads and follows — like onboarding a new team member by handing them a playbook. ## Getting Started ```bash openclaw plugins install @basicmemory/openclaw-basic-memory openclaw gateway restart ``` The plugin auto-detects your Basic Memory installation and starts working. If you don't have Basic Memory installed yet, it handles that too. From there, just talk to your agent. Say "remember that we decided to use Postgres for the new service." Say "what were we working on yesterday?" Say "create a task for the API refactor." The plugin handles the rest. [Full setup guide →](https://docs.basicmemory.com/integrations/openclaw){rel=""nofollow""}:br[GitHub →](https://github.com/basicmachines-co/openclaw-basic-memory){rel=""nofollow""} # When You Need Your Notes to Be Consistent One of the best things about Basic Memory is that you don't have to plan anything. You just start writing. Notes add up, ideas connect, patterns emerge on their own. That loose, organic quality is part of what makes it work. Your knowledge base grows the way thinking actually grows. But not everything benefits from that looseness. Some things need to be consistent every single time. A recipe should always list its ingredients. A task should always have a status. A meeting note should always capture who was there and what was decided. That's what schemas are for. ## What a Schema Is A schema is a template for a type of note. You define it once so your AI can use it every time a note of that type gets created or updated. Say you want every recipe note to include the cuisine, the number of servings, a list of ingredients, and the cooking steps. You tell your AI that once. It saves a schema. Now when your AI creates a recipe note, it has the structure available to work from. Like all things in Basic Memory, the schema itself is just a note. It lives in your knowledge base like everything else. You can open it, read it, edit it by hand. Your AI can read it too, whenever it's working on that type of note. Here's what a recipe schema actually looks like as a file: ```markdown --- title: Recipe type: schema entity: recipe schema: cuisine?: string, type of cuisine servings?: integer, how many it feeds prep_time?: string, how long to prepare ingredients(array): string, what you need steps(array): string, how to make it notes?(array): string, personal tweaks inspired_by?: Recipe, adapted from another recipe --- # Recipe Schema for recipes in the knowledge base. Every recipe should list its ingredients and steps. Cuisine, servings, and prep time are nice to have. Link to other recipes with `inspired_by` when one recipe builds on another. ``` A markdown file with some YAML and a description. The body text matters — it gives your AI the context to understand *why* a field exists, not just that it exists. The `?` means optional. The `(array)` means there can be more than one. `Recipe` with a capital letter means a link to another note. Simple declarations, no configuration files, no setup wizards. ## How to Create One Establishing a schema is as simple as telling your AI what you want. *"I want all my notes about my daily reading to include book title, author, page count, date of publication, my thoughts on the book, and a 1 to 10 rating of the book."* That's it. Your AI creates the schema note for you. Now it has a reference to work from whenever it's creating or updating a book note. If you've already been saving book notes for a while and want to bring consistency to what you've already written, your AI can figure out the pattern from what exists: *"Look at all my book notes and figure out what they have in common."* It analyzes your existing notes, finds the patterns, and proposes a schema based on what you've already been doing naturally. You review it, adjust anything that doesn't look right, and confirm. Then it can check your existing notes against the new template and offer to fix any that don't match. The result is that you end up with a consistent, reliable structure without having to design anything upfront. ## Keeping It Honest Over Time Notes evolve. Sometimes you start tracking things you didn't think to include at first. Maybe you start noting where you bought a book, who recommended it, or whether you're reading it alone or as part of a book club. You can ask your AI: *"Have any new patterns arisen from my reading notes?"* It compares what you've actually been writing to what the schema says. Maybe you've been adding a source field that isn't in the template yet. Maybe there's a field nobody uses anymore. It shows you the gaps and you decide what to update. Your schema stays honest to how you actually work, not how you planned to work six months ago. ## It Works for More Than Just Books Schemas are useful anywhere you want a repeatable shape. A few examples people actually use: **Task tracking.** Every task has a status, a priority, maybe a due date and a link to a project. You ask your AI to create a task, it fills in the right fields. You ask "what's still in progress?" and every task has a status field to answer from. **Meeting notes.** Who was there, what was decided, what happens next. Three months later you can ask "what did we decide about the API redesign?" and your AI finds the decision in exactly the place it expects it. **Research notes.** Source, key findings, open questions, connections to other research. Each note links to what it supports or contradicts. Over time you build a web of evidence that your AI can actually navigate. The point isn't that schemas make your AI smarter. They make your *information* more legible. When every meeting note has a `decisions` field, finding decisions is trivial. When some meeting notes bury decisions in paragraph three and others use a bullet list and others don't record them at all, your AI is guessing. ## Why This Makes Your AI More Useful When your notes have a consistent shape, your AI can answer questions with real precision. *"Show me all my pasta recipes that serve fewer than four."**"What tasks are still held up because John won't make a decision?"**"Who did we decide to follow up with after last Tuesday's meeting?"* Queries like this are reliable when every note of that type is structured the same way. Without that consistency, your AI does its best, but it misses things. Not because it's not smart enough, but because the information isn't where it expects it to be. Without a schema, maybe that information isn't there at all. Your AI wouldn't know to ask for page count, serving size, or any of the particulars you care about. You define the shape once, and the reliability follows. ## Make It Even More Reliable with Agent Skills Schemas work best when your AI knows to look for them. The `memory-schema` agent skill is a pre-built instruction set that teaches your AI to actively check for and follow schemas when creating or updating notes — making consistent structure much more likely in practice. You can install it alongside the rest of the Basic Memory skills: ```text npx skills add basicmachines-co/basic-memory-skills ``` [Learn more about agent skills](https://docs.basicmemory.com/whats-new/agent-skills){rel=""nofollow""} ## For the Nerds Everything above works through conversation — you talk to your AI, it handles the details. But if you want to understand what's actually happening under the hood, or you prefer working with the tools directly, here's how the schema system is put together. ### Picoschema Syntax Schemas use a compact YAML syntax for declaring fields. Each line is a field name, a type, and an optional description: ```yaml schema: name: string, full legal name role?: string, current job title works_at?: Organization, primary employer expertise?(array): string, areas of knowledge status?(enum): [active, inactive, alumni] contact_info?(object): phone?: string location?: string ``` The modifiers: | Syntax | Meaning | | ------------------------- | ---------------------------------- | | `field: type` | Required | | `field?: type` | Optional | | `field(array): type` | Required, multiple values | | `field?(array): type` | Optional, multiple values | | `field?(enum): [a, b, c]` | Constrained to listed values | | `CapitalizedName` | A link to another note (wiki-link) | Types are what you'd expect: `string`, `integer`, `number`, `boolean`, `any`. A capitalized name like `Organization` or `Project` means the field is a relation — a `[[wiki-link]]` to another note. ### How Fields Map to Notes Schema fields correspond directly to the observation and relation format Basic Memory already uses: | Schema Declaration | What It Looks Like in a Note | | ----------------------------------- | --------------------------------------------------------- | | `name: string` | `- [name] Ada Lovelace` | | `role?: string` | `- [role] Mathematician` | | `expertise?(array): string` | `- [expertise] Mathematics` and `- [expertise] Computing` | | `works_at?: Organization` | `- works_at [[Analytical Engine Project]]` | | `status?(enum): [active, inactive]` | `- [status] active` | Nothing new to learn. If you already know how Basic Memory notes work, schemas are just a way to say "this type of note should always have these fields." ### Schema Resolution When Basic Memory validates a note, it looks for a matching schema in this order: 1. **Inline** — a `schema:` dict defined directly in the note's frontmatter 2. **Explicit reference** — a `schema: Person` string pointing to a named schema note 3. **Implicit by type** — a schema note whose `entity` field matches the note's `type` 4. **No schema** — nothing found, validation skipped, and that's fine This means you can start with inline schemas while you're experimenting, then promote them to dedicated schema notes when the pattern stabilizes. ### Validation Modes Schemas support three validation modes, set in the schema's `settings`: | Mode | Behavior | When to Use | | ------------------ | ---------------------------------------------- | ---------------------------------- | | **warn** (default) | Reports missing fields, doesn't block anything | Active writing, gradual adoption | | **strict** | Treats missing required fields as errors | Mature schemas, enforced workflows | | **off** | No validation | Temporary, during restructuring | Start with `warn`. Move to `strict` once you trust the schema and want to enforce it. ### CLI Tools Three commands give you direct control: ```bash # Analyze existing notes and propose a schema from patterns bm schema infer person # Save the inferred schema as a permanent note bm schema infer person --save # Validate notes against their schema bm schema validate person # Check for drift between schema and actual usage bm schema diff person ``` `schema infer` is the interesting one. It reads all your notes of a given type, counts how often each field appears, and proposes a schema based on frequency. Fields that show up in 90% of notes become required. Fields that show up in 40% become optional. You review and adjust. ### A Complete Example The schema note (`schemas/person.md`): ```yaml --- title: Person type: schema entity: person version: 1 schema: name: string, full name role?: string, job title email?: string, contact email works_at?: Organization, employer expertise?(array): string, areas of knowledge settings: validation: warn --- # Person Schema for people in the knowledge base. Use `type: person` in your note frontmatter to match. ``` A conforming note (`people/ada-lovelace.md`): ```markdown --- title: Ada Lovelace type: person --- # Ada Lovelace ## Observations - [name] Ada Lovelace - [role] Mathematician and Writer - [expertise] Mathematics - [expertise] Computing theory ## Relations - works_at [[Analytical Engine Project]] ``` Validation says `✓ ada-lovelace: valid (0 warnings)`. Remove the `[name]` line, and you get `⚠ ada-lovelace: missing required field: name`. That's the whole system. Schemas describe your patterns, validation catches drift, and everything is just markdown files you can read, edit, and version control like anything else. [Full schema system reference](https://docs.basicmemory.com/concepts/schema-system){rel=""nofollow""} # A Side Project - and it actually works! > Originally posted to Reddit r/SideProject > {rel=""nofollow""} We got so fed up with AI forgetting everything that we built a (free, open source) solution, and it actually works! I've followed this sub for ages from my main account, so it's great to finally have something to post about. I've been totally fixated on the continuity problem with AI since I started working with it last year. Like everyone, I wanted to open each new conversation with a shared understanding of everything I'd ever discussed with Claude or Chat. I was constantly asking them to summarize conversations so I could paste them into the next chat. It was a pain in the ass, and each new conversation felt like a bad copy of the original. It wasn't just the content of the conversations that felt lost, it was the texture of it, the way we talked to one another. Claude (my favorite LLM by a mile) doesn't have "memory" in the way that ChatGPT does, but it hardly matters because for anything more than remembering a few facts about you, Chat's memory basically sucks. What it remembers feels arbitrary. And even when you say, "Hey, remember this" it remembers it the way IT wants to in a file you can delete by scrolling through all its memories in a buried setting, but you can't edit them. My friend Paul was having the same frustration at the same time. We were talking about it every time we hung out, and eventually he started building a solution for us to use. Once he had a working prototype, we met with amazing results right away. What started as a personal tool has grown into this free, open source project called Basic Memory that actually works (and now has over 1100 GitHub stars). If you follow AI at all, you've heard a lot about Model Context Protocol (MCP) servers. Basis Memory is a set of tools used via MCP. In a nutshell, users connect it to their Claude Desktop (or Claude Code), and whatever notes app they like that handles Markdown. We use Obsidian. Basic Memory takes detailed notes on your AI interactions that you two can reference in the future. Imagine a stenographer sitting in on all your chats writing notes about everything that's said and saving them locally, on your computer, so there are no privacy concerns. But what's really cool is that it's a two way street. You can edit the notes, Claude can edit the notes, he can create new ones, and you can too. All of them become part of your shared memory and what he draws on for every future conversation. Then whenever you want to revisit an old conversation or project, Claude reads your shared notes, almost all of which he wrote himself in language both of you can understand. The difference is night and day. Instead of starting from scratch every time, Claude picks up exactly where we left off, even weeks or months later. Research projects actually build on themselves now instead of resetting with every conversation. I made a (super basic, kind of awful) video showing how it works in practice. I'd love it if you check it out. We have a growing Discord community with a collection of avid users who have built wild new workflows around Basic Memory. It's been pretty cool seeing how people use it in ways that are way more sophisticated than anything we originally imagined. If you're working with AI regularly, it really does unlock so much more. It's worth checking out if the context loss problem drives you as crazy as it drove us. I hope it helps you as much as it's helped us. **Links:** - [GitHub repo](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} (AGPL, completely free) - [Installation guide](https://docs.basicmemory.com/getting-started){rel=""nofollow""} - [Discord](https://discord.gg/tyvKNccgqN){rel=""nofollow""} # Basic Memory: Simple Tools for Deep Collaboration There's a curious paradox in software development: sometimes the most powerful systems are built on remarkably simple foundations. At Basic Machines, we've embraced this philosophy with Basic Memory, creating a knowledge management system that relies on plain text files and straightforward tools rather than complex infrastructure. ## The Power of Plain Text The foundation of Basic Memory is intentionally minimal: markdown files in a normal directory structure. Each file can include semantic markup that's both human-readable and machine-parseable: ```markdown Building on [[Core Search]], we need to: - [tech] Add FTS support #implementation - [design] Consider pagination #todo - depends_on [[Database Layer]] ``` This format is both immediately useful to humans and structured enough for machines to understand. The double-bracket links create a wiki-like experience, while the categorized list items add semantic meaning that machines can interpret. Why does this matter? Because it creates a knowledge format that works equally well for both humans and AI without requiring either to adapt to an unnatural interface. ## Tools Over Infrastructure Many knowledge systems focus on building complex infrastructure - databases, servers, sync mechanisms. We've taken a different approach, focusing on tools that work with files directly: ```python # Read content with metadata content = await read_note("docs/components/search") # Find related documents related = await read_note("docs/search/implements/*") # Build deeper context with semantic graph context = await build_context("specs/search", depth=2) ``` These tools handle tasks like reading files, following semantic relationships, pattern matching across documents, and building contextual understanding. The emphasis is on simple interfaces that perform powerful operations, not complex infrastructure that's difficult to understand or modify. ## Natural Knowledge Building Knowledge in Basic Memory accumulates through normal use, not through special ingestion processes: 1. Write markdown files with natural references to other topics 2. The system understands these semantic connections automatically 3. Tools can follow these relationships to build context 4. Pattern matching finds related content across your knowledge base This creates a remarkably natural workflow - just write normally, and the connections between your ideas are captured without additional effort. ## Enabling Human-AI Collaboration This simple foundation enables surprisingly effective collaboration between humans and AI systems: 1. **Context Building**:br AIs can follow document relationships, understand semantic markup, and track changes over time, giving them rich context for conversations. 2. **Natural Interaction**:br Since everything consists of standard text files in familiar formats, both humans and AI systems can read and write without specialized interfaces. 3. **Composable Tools**:br The tool-based approach means functionality can be combined in different ways to solve different problems, rather than forcing everything into a monolithic application. ## Why This Matters The interesting part isn't the individual pieces - it's how they work together to enable genuine collaboration: **For humans**, it's just markdown files. Write them in any editor, store them in git, use normal tools to work with them. No need to learn complex interfaces or workflows. **For AI systems**, the semantic structure provides clear navigational paths, and the file-based approach creates natural boundaries around concepts. **For both**, having a shared medium that works equally well for human and machine intelligence creates opportunities for collaboration that aren't possible when each is forced to use interfaces optimized for the other. ## Technical Foundation It's worth noting that the system builds on proven, stable technology: - SQLite for searching and indexing - Markdown for content - Standard file operations - Git compatible for version control This means it's built on tools that have been extensively tested and are likely to remain viable for decades, not proprietary formats or services that might disappear. ## Simplicity as a Feature In an era where software increasingly becomes more complex, there's significant value in intentional simplicity. By building on files and focusing on tools rather than infrastructure, Basic Memory achieves several important qualities: 1. **Durability**: Text files have remarkable staying power compared to proprietary formats 2. **Hackability**: Simple systems are easier to modify and extend 3. **Portability**: Files work anywhere, with minimal dependencies 4. **Transparency**: The operation of the system is easy to understand and predict In the end, this approach shows how simple tools built on standard technology can enable sophisticated collaboration between humans and AI systems without requiring either to conform to unnatural interfaces or workflows. Sometimes the most powerful systems aren't those with the most features or the most complex architecture, but those that get the fundamentals right and then get out of the way. --- Want to explore Basic Memory for yourself? Check out our [GitHub repository](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} to get started. # Your AI Can Now Filter Your Notes Like a Spreadsheet If you've been using Basic Memory for a while, your notes already have labels on them — your AI has been adding them automatically. Things like `status`, `type`, `tags`. You may not have even noticed. These labels live in a small block at the top of every note called **frontmatter**. It looks like this: ```yaml --- title: Website Redesign status: in-progress priority: high assigned: sarah tags: [design, q2] --- ``` Until now, those labels were treated like any other text in your notes. Frontmatter wasn't special. Searching for "in-progress" meant searching for that phrase everywhere - in note bodies, in headings, in labels — and hoping the right things came back. With the newly released v0.19, frontmatter is special. Your AI can now filter by those labels precisely. ## Plain English Works You don't need to learn any new syntax. Ask your AI the way you normally would: *"What are my active tasks?"* *"Show me everything marked high priority."* *"Find all my notes tagged with 'client-work'."* Your AI translates those questions into precise label lookups. Behind the scenes it's reading your frontmatter and returning exact matches. ## It's Your System Basic Memory doesn't tell you what labels to use. You make up whatever makes sense to you. - A project manager might use `status`, `owner`, `deadline` - A novelist might use `pov-character`, `timeline`, `draft-status` - A researcher might use `read-status`, `relevance`, `cited-by` To add a label, ask your AI — *"Add 'status: active' to this note"* — or open the file in any text editor and add the frontmatter yourself. Both work. The file is always yours to edit. ## For Developers and AI Agents *The plain-English experience above is powered by new `metadata_filters` support in `search_notes`. Here's what's actually happening:* Before v0.19, frontmatter fields were indexed as text, so `search_notes("status: active")` was an unreliable string match — not a field query. v0.19 introduces first-class metadata filtering that maps directly to SQLite queries on indexed frontmatter fields: ```python # Exact field match search_notes(metadata_filters={"status": "active"}) # Multiple fields (ANDed by default) search_notes(metadata_filters={"status": "active", "priority": "high"}) # Set membership search_notes(metadata_filters={"priority": {"$in": ["high", "critical"]}}) # Date range search_notes(metadata_filters={"completed": {"$gte": "2026-02-01"}}) # Numeric range search_notes(metadata_filters={"sprint": {"$between": [10, 15]}}) # Combined with semantic search search_notes(query="API refactor", metadata_filters={"status": "active"}) # Tag shorthand search_notes(tags=["backend", "q1-2026"]) ``` Available operators: `$in`, `$gt`, `$gte`, `$lt`, `$lte`, `$between`. Work on strings, numbers, and dates. [Metadata search reference →](https://docs.basicmemory.com/concepts/semantic-search#metadata-filters){rel=""nofollow""} [How-to: note-taking with metadata →](https://docs.basicmemory.com/how-to/note-taking#metadata-search){rel=""nofollow""} # Text-based Knowledge Systems: Finding the Natural Interface for LLMs In developing Basic Memory, we discovered something fundamental about how Large Language Models interact with knowledge systems. While we initially set out to create a personal knowledge management tool, we inadvertently stumbled upon what might be called the "native file format" for LLM cognition – structured text with semantic relationships. Current knowledge systems for AI tend to fall into one of several categories: - **Databases**: Highly structured but lose the nuance and contextual richness that LLMs need - **Document systems**: Human-readable but lack explicit semantic relationships - **Vector databases**: Focus on similarity but miss explicit connections - **Knowledge graphs**: Relationship-focused but often too rigid for natural language processing Each approach optimizes for either human readability or machine processing, but rarely both. This creates a fundamental mismatch with how LLMs actually work. What makes Basic Memory different is that it's effectively "bilingual" – speaking both human language through familiar Markdown text and LLM language through semantic observations and relationships. ```mermaid graph LR M[Markdown Files] <--> KG[Knowledge Graph] subgraph "Human Interface" M E[Text Editors] O[Obsidian] end subgraph "AI Interface" KG Q[Queries] C[Context Building] end E --> M O --> M KG --> Q KG --> C class M,E,O human class KG,Q,C ai ``` LLMs, despite their sophisticated capabilities, fundamentally operate on text. They were trained on text, they predict text, and they understand the world through text. When we provide tools that transform context into textual representations, LLMs can work with them much more naturally than with abstract data structures. This realization came through practical experimentation rather than theoretical design. When we implemented Basic Memory with Markdown as the primary format, adding just enough structure for semantic relationships, we found that both humans and LLMs could interact with it naturally. The key insight is finding the right balance: - **Text-based at its core**: Keeping the primary medium as text that LLMs can process natively - **Lightly structured**: Adding just enough semantic relationships for navigation - **Human readable and editable**: Using familiar formats that people can work with directly - **Bidirectionally accessible**: Ensuring both humans and AI can read and write This balance creates what we might call "cognitive compatibility" – aligning with how both humans and LLMs naturally process information. This approach has several practical benefits: 1. **Natural interactions**: LLMs can reason about and generate knowledge more fluidly 2. **Easier maintenance**: Humans can directly edit and understand the knowledge base 3. **Lower complexity**: Simpler systems with fewer specialized components 4. **Better alignment**: Knowledge representation that matches how both parties think 5. **Persistence with meaning**: Information retains both its content and its context As AI systems continue to evolve, this principle of text-based knowledge with semantic structure may become increasingly important. Rather than forcing LLMs to adapt to rigid database schemas or complex object models, we can create knowledge systems that work with their inherent capabilities. Basic Memory represents one implementation of this principle, but the broader insight about the "native file format" for LLM cognition could inform many aspects of AI system design going forward. The most effective AI tools might not be the ones with the most sophisticated data structures, but those that find the right balance between human readability and machine navigability – working with the grain of how both humans and LLMs actually think. Sometimes the most important discoveries come not from theoretical breakthroughs but from practical experimentation. In developing Basic Memory, we weren't setting out to create a new paradigm for knowledge representation, but by listening to how LLMs actually interact with information, we found an approach that feels natural to both human and artificial intelligence. The future of AI knowledge systems might not be about increasingly complex structures, but about finding that sweet spot where text and semantics meet – creating interfaces that bring joy to both human and AI users. --- Want to explore Basic Memory for yourself? Check out our [GitHub repository](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} to get started. # Try the New Basic Memory Web App In February I wrote about the new editor. That post ended with a promise: the browser needed work too, and we weren't done. Today we're done with that part. We rebuilt the entire web app: the workspace you browse notes in, the way you share them, the history behind every file, and a new way to see your knowledge graph. It's live now, and you should go try it. This came out of months of talking to people about how they actually use Basic Memory, not how we pictured them using it. The pattern was consistent. People browse projects, jump between connected notes, search for something half-remembered, and try to see how it all fits together. The old app made every one of those harder than it needed to be. So we fixed it. ## The Redesigned Workspace The first thing you'll notice is that it looks better. That's not the point, but it's true, and it matters. A tool you find ugly is a tool you open less. What changed is underneath. Browsing is faster. **Pinned notes** stay where you can reach them. You can switch between **list and gallery views** depending on what you're doing: list when you're working through notes methodically, gallery when you're hunting for something and a wall of titles isn't helping. ![The redesigned notes workspace](https://basicmemory.com/images/blog/web-app-workspace.png) If you've used a note-taking app before, none of this needs a tutorial. That was the goal. The structure underneath (entities, observations, relations) is exactly what it was. We just stopped making you fight the interface to get to it. ## The Editor, In Its Place The ProseKit editor we shipped in February is still here: live, preview, and source modes, wikilink autocomplete, the slash menu, the keyboard shortcuts. If you missed that one, the [February post](https://basicmemory.com/blog/basic-memory-cloud-february-2026-release) covers it in detail. What changed is the workspace around it. Frontmatter editing, rich text, Markdown source, and preview are all a keystroke apart. After February the editor was the best part of the app. Now the rest of the app caught up to it. ## Search That Keeps Up Search is faster and more accurate. Since v0.19.0 it's been semantic by default, so you can ask for "login security" and find the note that says "authentication hardening." This release is about the part you feel: results come back fast enough that you keep typing instead of waiting. ## Public Note Sharing This is the one I'm most glad to ship. You can now **share a note publicly**, the way you'd share a Google Doc. Send someone a link. They read the note. No account, no install, no exporting to a PDF that's stale the moment you make it. ![Public note sharing](https://basicmemory.com/images/blog/web-app-public-sharing.png) Basic Memory has always been about knowledge you own. Owning it shouldn't mean it's trapped. If you've built up a researched answer, a runbook, or a decision record, you can hand it to someone now without handing them your whole knowledge base. ## Version History, Per File Every note now has **per-file version history**. You can see how a note changed over time and what it used to say. ![Per-file version history with a side-by-side diff](https://basicmemory.com/images/blog/web-app-version-history.png) This matters more with AI in the loop. When you and an LLM are both writing to the same notes, "what changed, and when" stops being a nice-to-have. It's how you trust the system. History makes the collaboration auditable instead of mysterious. ## The Connective Tissue A few things that don't each need their own section but add up: - **Mermaid rendering.** Diagrams in your notes render as diagrams, not code blocks. - **Imports.** Getting knowledge in stays easy. - **Snapshots.** Point-in-time captures of your whole knowledge base. - **Live activity updates.** Changes show up across devices without a manual refresh, so the note on your phone matches the note on your laptop. None of these are headline features. Together they're the difference between an app you check and an app you work in. ## Seeing the Graph Your notes have always been a graph: observations and relations, things you know and how they connect. Until now you mostly had to take that on faith. The new **graphing and visualization tools** let you see it. The shape of what you've built, the clusters, the connections you forgot you made. ![Knowledge graph visualization](https://basicmemory.com/images/blog/web-app-graph.png) This is the feature nobody asks for and nobody stops using once it's there. Knowledge you can see is knowledge you can reason about. ## One More Thing: Basic Memory Teams Everything above is built for one person and their AI working a knowledge base together. A lot of you wrote in asking the obvious next question: what about my team? This week we're opening invitations to the **Basic Memory Teams beta**. Teams gives your organization a shared workspace, so teammates and their AI agents build on the same notes and the same knowledge graph. You get sharing controls, versioning, and real-time collaboration between humans and LLMs, and your organization keeps full control of its knowledge. If you've been waiting for this, [email us](mailto\:hello@basicmemory.com?subject=Basic%20Memory%20Teams%20beta) for a 30-day free trial. ## Why We Built This Basic Memory exists because your knowledge should live in plain text you control. That hasn't changed and won't. But "plain text you control" was never supposed to mean "the tools for working with it are mediocre." The local experience, your own editor and filesystem and backups, is still first-class. For people who want cloud sync, AI integration, and access from anywhere, the web app should be just as good. I've been living in it for weeks and I don't find myself wishing I were back in my local setup. That was the bar. ## What's Next We're not done. We're never done. But the gap between Basic Memory the idea and Basic Memory the app you actually open is the smallest it's ever been. Go see for yourself. If you're already on Basic Memory Cloud, the new app is live. [Check it out here](https://app.basicmemory.com){rel=""noopener,noreferrer""}. It's now the default Basic Memory experience. Try Basic Memory free at [basicmemory.com](https://app.basicmemory.com/auth/signup){rel=""nofollow""} --- **Further Reading:** - [Basic Memory Cloud February 2026: A Real Editor, Finally](https://basicmemory.com/blog/basic-memory-cloud-february-2026-release) - [Basic Memory v0.19.0: Search That Understands What You Mean](https://basicmemory.com/blog/basic-memory-v0-19-0-release) - [GitHub - basicmachines-co/basic-memory](https://github.com/basicmachines-co/basic-memory){rel=""nofollow""} - [Basic Memory Documentation](https://docs.basicmemory.com){rel=""nofollow""} # The Problem with AI Memory (and How We Fixed it)* This morning, I was emailing with an AI YouTuber in response to a question about what makes Basic Memory different from Chat’s memory system and what we presume will be Claude’s Memory, if and when they get around to releasing it. I found myself writing at such length on the topic, I thought it might be a good idea to write more about it here. [Note: They did, read our take here](https://basicmemory.com/blog/claude-memory). Anyone learning about Basic Memory for the first time might say, “Chat already remembers stuff about me.” And, certainly, that’s true. It does remember some things. But not in a way that belongs to you or delivers the highest value. Let’s look at a few examples of conversations that are impossible with Chat’s memory system that are a breeze for Basic Memory. ::div --- class: bg-gray-50 dark:bg-zinc-800 border border-gray-200 dark:border-zinc-700 rounded-lg p-4 my-4 font-mono text-gray-900 dark:text-zinc-100 --- \> User: Where did we land on the authentication approach for the user dashboard? Seems like we were just talking about it. AI: Right. That was last Tuesday. You were leaning toward OAuth 2.0 but worried about the complexity for your team. Should we look into simpler solutions? I can show you a list of the concerns you brought up before if you like, along with the alternatives we discussed. :: ::div --- class: bg-gray-50 dark:bg-zinc-800 border border-gray-200 dark:border-zinc-700 rounded-lg p-4 my-4 font-mono text-gray-900 dark:text-zinc-100 --- \> User: I know we've brainstormed a lot about my anniversary trip, but it's been months, and I've totally lost the thread. What did we narrow it down to? AI: When we last discussed it in May, you were debating between a mountain getaway, a rustic beach hut, and a penthouse in Chicago. You were leaning towards that lodge in Colorado. You shared the links to the Airbnbs you were considering. Would you like to see those now, or do you have some new destinations in mind? :: ::div --- class: bg-gray-50 dark:bg-zinc-800 border border-gray-200 dark:border-zinc-700 rounded-lg p-4 my-4 font-mono text-gray-900 dark:text-zinc-100 --- \> User: Please initiate Enhanced Startup Protocol B3, then check out our notes about that file corruption issue. Once you understand the problem, review this document and flag what needs fixing. AI: Protocol B3 activated! I remember that corruption mess from last week. Give me a moment to scan the document... :: If you look at Chat's memory, you’ll see things like "Drew lives in Austin" or "Drew hates tomatoes." A really beefy memory in Chat's database might explain a specific project or even some details about it. Some of those memories are even helpful, but their inevitable incompleteness can also work against you. Given limited information, LLMs begin filling in the blanks with what “feels” to it like the logical middle, even if it’s completely incorrect. They start making weird, incorrect assumptions. But what can you do? You can’t edit memories in Chat. You can only delete them. If, that is, you can find them in a lengthy scroll of (unsearchable) memories. Basic Memory takes a drastically different approach. I like to use the image of a stenographer sitting in on all your chats and taking detailed notes on all your interactions. The notes are finished the moment the conversation ends, written in plain text you and your LLM can both read, search, and edit. You can also write notes or add context independently that your LLM will use thereafter. It’s all part of your second brain that grows as you do. Every note becomes part of a semantic knowledge graph that discovers connections that prove invaluable over the life of any project, even if that project is just day-to-day living. These aren’t bullet points or lists. They’re fleshed out notes that make sense of what you’re trying to achieve and where things stand, not merely as “facts,” but as entries in a narrative that also take temporality into account. With Basic Memory, you can understand when you arrived at a decision and by what logic. It’s not separated into two talking points like “Drew is debating buying the Japanese movie poster for Pump Up the Volume,” and “Drew is the proud owner of a Japanese movie poster for Pump up the Volume.” Your notes hold all the data in between, making sense of the trajectory of thought and experience that led you to the present circumstance. That’s not all that gets lost in a typical LLM chat. In my experience, and the experience of several of our users, chats with AI have a quality that might best be described as “shaggy.” That is to say, they’re meandering, unpredictable, and spontaneous. You start off talking about a professional project, briefly ruminate about an ex, fantasize about a business idea, then return to that professional project. If you want to revisit that brilliant idea sandwiched between other things, you might never find it again. But with Basic Memory, conversations don’t have to be tidy or neat to be remembered. Like a kind of informational stew, everything goes in. But all of that is merely a precursor to a linchpin notion that is central to the entire Basic Memory project and ethos: **At Basic Memory, we believe your information should belong to you.** All of it. And not buried in json files you can request from a vendor or hidden away in vector databases. These are your chats, your ideas, and your discoveries. They should be accessible, truly readable, and under your control. That’s what Basic Memory makes possible. Reddit is filled with stories of people who find themselves inexplicably barred from Chat or Claude. Usually (at least in the cases I’ve seen), it’s an error. Do they ever recover their chats, who knows? But it seems crazy to surrender that much power and trust to entities whose customer service reps are notorious for being all but unreachable no matter how desperately you try. For many of us, our AI chats are where our ideas now live. What’s more important than protecting that? So, again, how is Basic Memory different than an LLM’s memory? In just about every way. It’s exhaustive instead of reductionistic, temporal instead of based on static facts, editable instead of locked down. It’s searchable, it draws connections you might never have drawn, you can write and edit your own “memories,” and, most importantly, it’s YOURS. If you check out our [Discord](https://discord.gg/tyvKNccgqN){rel=""nofollow""}, you’ll see our users utilizing Basic Memory in such wildly unexpected ways—from a guy using it to make music, to coaches using it to track the progress of their clients. We recently talked to one user making a (quite complex sounding) dream tracking system and another sharing his Basic Memory vault with a team of 6 to 7 people as they carry out deep data research. As we prepare to launch Basic Memory Cloud, our thoughts are on all these issues, in the hopes that Cloud will open up even more possibilities to our users. If you haven’t tried Basic Memory yet, we’ve just released a very straightforward one-step install process. You can find our videos about it here: {rel=""nofollow""} And, truly, check out our [Discord](https://discord.gg/tyvKNccgqN){rel=""nofollow""}. It’s filled with inspiring use cases and some fascinating characters doing things we never would have imagined. *\*Obvious Clickbait Headline: AI Memory is an unsolved problem, we are working on it.* # Your Notes, Your Bucket: The Storage Layer Behind Basic Memory Cloud This week, Tigris posted a terrific case study about Basic Memory, our philosophies around AI memory, and why we chose Tigris as the storage layer behind Basic Memory Cloud. As our users know, Basic Memory is built around a simple idea: your memory should belong to you. That means plain Markdown files, storage you can inspect and move, and cloud infrastructure that preserves portability instead of hiding your knowledge inside an opaque system. Tigris helps us make that work in Basic Memory Cloud by giving each user isolated, S3-compatible storage, with sync, snapshots, and file history built on top. They're also a smart, thoughtful company that seems to run with the same kind of energy we try to bring to our own work. When we email them, they reply. When we talk about what we wish Tigris could do, they give us great advice, and half the time we realize they already offer what we're asking for. We just didn't know it yet. It was a pleasure connecting with Katie Schilling and David Myriel, who wrote the piece. They took the time to really understand Basic Memory, and their case study gets into the technical choices behind the product, including per-tenant buckets, rclone sync, bucket snapshots, and how those primitives let us build cloud features without giving up user ownership. We're reposting it here for readers who want a deeper look at the infrastructure choices behind Basic Memory, and the philosophy behind them: AI memory that belongs to you. If you're at all interested in the details of AI memory, it's worth a read. [Read the full case study on Tigris →](https://www.tigrisdata.com/blog/case-study-basic-memory/){rel=""nofollow""} # We’re in the ChatGPT Plugin Directory and the Claude Connector Directory Basic Memory Cloud was published in both the ChatGPT Plugin Directory and the Claude Connector Directory—on the same day! That means we’ll now show up in searches for approved apps and connectors within both ChatGPT and Claude. The connection process will be more seamless, and more people will be able to connect their AI tools to a persistent knowledge base they can actually read, edit, search, and own. All without spiraling down the “custom connector” rabbit hole that we’ve long worried might be hanging up some of our users. We’re really chuffed to be “in.” Doubly so because the not-so-fun process is finally over. From the outside, applying to one of the big AI app directories sounds simple enough. Fill out the form, write the description, upload a logo, provide a test account. In practice, it required a lot more thinking and doing than that. We first applied to the Claude App Directory six months ago. SIX. MONTHS. AGO. There were forms, review requirements, technical details, test instructions, and lots of back and forth among the Basic Memory team about how the application should be put together and how to make it clear, within a limited character count, what we’re all about. The ChatGPT Apps submission was accepted a hell of a lot faster, just one week, but it had its own hoops. At one point, Paul had to track down an Android emulator just to put the app through its paces for a required demo video. That’s probably the moment when the whole thing crossed from “slightly painful” into “comically annoying.” But the hoops make sense, even when they’re frustrating. If every app that applied got approved automatically, the directories would be flooded with half-baked projects. Frankly, a few may have slipped in already. Not that we judge. Part of the complexity is that Basic Memory is not just a button that does one thing. It lets users, collaborators, and AI tools search, read, write, and update a shared knowledge base. That knowledge base can be as simple or as complex as each user needs it to be. It’s a pretty substantial toolkit. All that to say, yes, it was a little rough. But for the moment, we’re just relieved it’s over. And we hope our new users enjoy the convenience that wasn’t available to our early adopters. Just search for “Basic Memory” and… click! ## Connect Basic Memory - [ChatGPT Plugin Directory guide](https://basicmemory.com/for/chatgpt) - [Claude Connectors Directory guide](https://basicmemory.com/for/claude) # What is Basic Memory? This is a question I get a lot. Honestly, I don't know how to really answer it. It's a lot of things. It has a silly name. It has simple features, like reading and writing notes, so it is basic, but it really does do some powerful things. It also has "memory" in the name, so it obviously is supposed to help you remember things. It lets AI agents write notes to text files in Markdown. It indexes them for searching, then syncs them again when a user modifies them. That sounds basic, for sure. It also does some other things, which, even though they are simple, can actually get pretty complicated. It parses and traverses all of the notes to create a semantic knowledge graph that can be queried and traversed recursively. What does that even mean? Why should you even care? The answer, maybe you don't care, and certainly you shouldn't need to really understand "how" it works under the covers. It's a tool, and the most important thing about a tool is that it should "just work". When something works well, it gets out of your way and enables you to do what you set out to do more easily. Really that's what Basic Memory aims to be, a tool that works well enough to help organize your long term memory, with AI. But why do I even need this tool? How is it useful? > This is the backstory, so feel free to skip to the end if you'd rather. To answer this, I'll start at the beginning (of me chatting with AI LLMs (Large Language Models)). When I first started chatting (using ChatGPT), It seemed like the conversation could go on forever. It was really amazing, I could just talk to this "thing", and it would answer back. Sometimes garbage, but other times with really useful or helpful information. I started trying to talk to it about a lot of things, ideas I had, questions. Then, because I'm a software developer, programming. I was shocked, truly, to see that it could write a lot of code pretty well. Not everything, but then again, neither can I, and I've been a professional developer for a long while (decades). As I went deeper and deeper into "knowledge activities" with it, learning new code, using it to help me write React code, then eventually, just letting it write the code entirely, I began to hit some walls. Things would be going great, and the chat would hit a limit. No more messages in the conversation. Crap. So, I did what anyone might do, I copy pasted a whole bunch of chat info to a local text file, then started a new chat and pasted it back in. Back in business. But that got old really quickly. Soon, I had a huge mess of notes, and a bunch of chats with a lot of repeated information. What I wanted was one place to store all of it so I could manage it more easily. At this point, I stumbled across Claude. It was even better at coding than ChatGPT, and it had this funky "personality" to it. Using it was actually fun. And, it had this cool feature, called Projects, where you could upload files and the chat could already see the info, without me having to copy/paste (Claude Projects allows the LLM to load info into its context window before a chat starts). That was a huge improvement, but, I still had to copy and paste as things got out of date, or maybe I'd forget something was in the Project info, but incorrect, or not relevant, and oh, where is that in the Project? It was hard to search. So, I decided to try and build my own version of Projects, and maybe figure out how to use the api to read it. I really didn't know. But, I had already been using AI assistants to make all sorts of code projects I would have not been able to do otherwise (that's another story). Now, I didn't know how or what I was going to do, but I had a problem, and one I could see lots of other people were going to have when they used LLMs for chatting, how do I organize all the knowledge that is getting produced? And how do *I* keep it, instead of it being *up there* where I can't work with it easily. Then, late last year, Anthropic released the MCP (Model Context Protocol) spec. Like I said, I'm a programmer, so I'm fairly used to reading specification docs. But I had to read this one about three times before I understood (most of) it. And, there were all these sample apps they released that did really cool things! Tools to read and write local files (filesystem mcp), one that stored a semantic knowledge graph in local json files (memory-json mcp). They were all open source, I could just grab the code and run them. Right away, I could see this is what I needed. I've been a long time Obsidian fan, and have used Markdown for my daily notes for personal and work information. The idea came really naturally then, what if I could keep memories, like the memory-json, but in Markdown? Obsidian uses markdown to let people create a "second brain" of linked knowledge, what about a Zettlekasten for AI? I thought I was a genius. It would be so simple. I'll bet I can do it in a week. Well, a few months later, and I did have something that worked well enough to share with some friends. I was as amazed as anyone, maybe more, when it worked as I'd envisioned. Mind you, the features were limited and there were plenty of bugs. But, Basic Memory would let the AI write Markdown files, and I could see them immediately right inside Obsidian. Then, I could update the file and the AI could see my updates. ## Aside: Building Basic Memory Perhaps one of the more interesting parts about all of this is that I used AI extensively to build Basic Memory from the very beginning. It's a truly native AI software project. Not a vibe coded project, a real software project, like every other one I've built professionally, with clean code, tests, architecture docs, etc. And, we (the AI and myself) used Basic Memory together keep track of what we were building as we built it. We dogfooded it from the beginning, a software term meaning "eating our own dogfood", or using the thing you are trying to build as you build it. So, Claude and myself were, in fact the first users. There was no great plan, it changed as we went and we just kept building. At one point, I refactored the code (meaning changed the implementation), and removed half of it, after we discovered a better way to implement a feature. The other interesting part of this anecdote is that Claude loved the idea. I know now, it's fashionable to say that AIs are sycophantic and they love everything, but trust me, we had a lot of conversations where the AI shot my bad ideas down. What happened here is kind of special, at least it was for me. Because the AI (Claude) was enthusiastic about the idea of Basic Memory, and I told it we were very much collaborating, and I needed it's best and most honest opinion, it gave them to me. It helped me connect the dots between different concepts that I wouldn't have done alone otherwise. For instance, in any complex software project with a lot of data, there needs to be one thing that is the "source of truth", otherwise, if for instance a file says one thing, but the version indexed for the search in the database says another, what do you do? We came up with a bunch of rules, the filesystem is always the source of truth, versioning should be simple, like git, etc. We wrote all of these down in Basic Memory, then we could reference them again. And these notes were very detailed. One of the instructions I gave was to "use prose" to explain, not lists. And what I got out was a lot of really detailed design notes with extensive depth about how the system was related and interconnected. And, the notes themselves were connected! Then, I decided I had to just get *something* out, meaning release some version so other people could use it and I could hopefully get feedback. Of course, as a software developer, I know that releasing is actually the beginning of the pain and hard work that comes with a software project. Next, when people start actually using it, they find bugs and you have to fix them, and keep trying to build more features. Luckily, lots of people have found Basic Memory and started using it. I hear from new people all the time, and that is really wonderful. People file bug issues on github and make enhancement requests asking for more features. ## So what did we end up building? Now, why is Basic Memory useful, and what are these magical features? Like I said, the idea is to keep things simple. But also, to make a set of really simple tools that work together and contribute to create something that is very powerful. At its core, Basic Memory does three simple things that work together to create something powerful: 1. **Stores knowledge in plain Markdown files** - Everything lives locally on your computer, not in some cloud database. 2. **Creates connections automatically** - Every connection becomes searchable and traversable 3. **Enables two-way collaboration** - True two-way collaboration in plain text between AI and humans Basic Memory has a few common tools: `read_note`, `write_note`, `edit_note`, `search_note`, etc. These let the AI write information in Markdown to files on your local computer filesystem. The user can see these notes and read them, modify them, move them, combine, or delete them. All of this is synced back into the system so the AI can see your changes. All of the notes get indexed into a local search index, so you can query them easily. Also, the notes have some special formatting that the code parses and indexes into a graph (a set of connected objects, like a tree) that Basic Memory can query recursively (one result, leads to more results, and so on). The Markdown system has a few special, again simple, conventions to enable this: - Each note is an "Entity", or a thing, that can contain a bunch of text. - Entities can contain "Observations", or facts about that thing. These are simple markdown lists, like `- [category] Some fact`. - Entities can be related to each other via links. Basic Memory uses the `[[wikilink]]` convention to relate notes (Entities). These can also contain extra information to describe the type of relationship and context. The tools the AI uses all have special instructions, so it knows all about these things and can write notes with the special formatting so all the things are connected. Now, using these simple things, a user can ask an AI assistant in a chat "What were we discussing about `` last month?", and the AI can use the tools to search the data in Basic Memory, then find other things related to results, and know *how* they are related semantically (how a thing is understood), because the Markdown documents contain the information. All of this is just plain text (Markdown), and is easily read by humans as well as AIs. It turns out, also, that this is very convenient for a couple of reasons. First, the "context window" or size of information within a conversation with an AI is limited. They are very large, and continue to grow but still, you can't fit everything in there all at once. So, it's helpful to be able to find relevant information easily and load it and it's related information into the context window (new chat) easily. This is how Basic Memory enables "persistent, interconnected knowledge". Second, it enables a "common interface" between AIs and humans that they both understand really well, plain text! And, because Basic Memory files are easily editable and sync automatically back into the system, there is a *real* two way information exchange enabled for long term, deep information between humans and AIs. This is what I mean when I say that your knowledge "grows with you". You aren't limited to what the AI decides to save for important "memories" in its own data store. And you aren't confined by how much data you can store, it's just files. Now, then, what we have is a system, made of relatively simple parts, that is actually quite sophisticated. Basic Memory creates a set of tools and a process where you have a lot of potential to build, collect and manage rich knowledge together with an AI. It doesn't force you into some sort of thing that is difficult to use. And, it doesn't try to hide information or format it in a way that is hard to understand. There is no black box. You can see everything, and you can control everything. There is a lot more work left to do, and I am really looking forward to adding even more features to Basic Memory. I really hope that, with this latest release people will continue to find Basic Memory useful, and it gets out of their way and is just helpful. All feedback is appreciated, or maybe considering telling a friend. Thanks for reading, -Paul # A Look Back at Year 1 of Basic Memory A year ago, Anthropic released the MCP standard. Paul started tinkering with it over that Thanksgiving weekend, and he's been obsessing with Basic Memory ever since. Today, Basic Memory is a four-person team building a knowledge platform that serves as your "ground truth." The formula is simple: it's all just plain text. You can read it, you can write it, you can update it, and you can delete it. Underpinning these capabilities lies the Holy Trinity of Basic Memory: ENTITIES, OBSERVATIONS, and RELATIONS. These enable the AI to understand how your data is related, what's important, and how it all fits together across conversations. Save your knowledge, connect it, own it forever. That's the idea. ## What Basic Memory does now Basic Memory works across LLMs—Claude, ChatGPT, Gemini, Cursor, Claude Code. It runs locally or in the cloud. Desktop, phone, or on the web. Your notes live in plain Markdown, fully portable, always yours. Behind the scenes, this past year we've moved from indexing notes into SQLite to dynamic Postgres instances per user, which means machines don't fall over under load. We've switched from local storage to cloud buckets that can grow with your workspace. We've spent hundreds of hours tuning the MCP interface so LLMs actually know how to use your knowledge effectively. When Basic Memory "just works," it's because we're doing the hard work of steering the AI to find what you need. We've also built migration tools (upload notes individually or in bulk, one-way sync, bidirectional sync) because getting your knowledge in should be easy. And getting it out should be even easier. Download everything as Markdown anytime you want. Your knowledge is 100% portable. On the surface, Basic Memory doesn't look massively different than when we launched it, apart from the themes (which honestly ARE a game changer). Under the hood, it's a completely different machine. ## How we got here Early on, Basic Memory was a local-first memory layer for Claude Desktop. The problem was simple: Claude's integrated memory was limited, and your notes were locked inside a corporate system. If you wanted to save conversations, you had to use awkward browser extensions or rely on AI-generated summaries that were usually garbage by the time you thought to create them. We saw the same thing everyone else saw: AI needs better memory. A massive number of tech nerds and giant conglomerates started building solutions. We kept evaluating them and kept arriving at the same conclusion: what we're doing is better. Why? Because we understood something fundamental: whether you call your input an agent, a hook, a skill, or whatever else, it's all just text. Once you see that—once you understand that all you really need is a source of truth—you see why Basic Memory works the way it does. The grind was real. We added project support so you could organize different domains of knowledge. We made installation easier. We got it working with Claude Code (thank God). We prepared for cloud deployment and added support for multiple LLMs and frameworks. Then we did customer interviews. More than twenty users spent their time talking with us about how they used the open-source project and what they wanted in a cloud version. The interviews were as validating as they were illuminating. Our users wanted the same things we wanted: a system that was affordable, usable anywhere, that works across LLMs and devices. And they wanted to maintain control of their information. So that's exactly what we built. Moving everything to the cloud without making it suck was harder than it sounds. Our users were incredibly patient and helpful during the process. In a landscape where people are constantly chasing shiny new projects, our users have been faithful and engaged. I think that's because they get it: they understand the value of a reliable source of truth. We've also stayed committed to user privacy and control. Your data stays isolated per user. We maintain rigid boundaries in the cloud, which is its own set of challenges, but it's non-negotiable for us. ## What we're working on We plan to elaborate on our roadmap in an upcoming post, but in simple terms, our focus going forward is the same: more capabilities, more control, more reliability, greater simplicity. All while adding more features and depth. If you haven't looked at Basic Memory lately, now's a good time. If you're already using it, just know there's more coming soon, and we're excited to share it with you. In the meantime, if you have a feature you'd like to see in Basic Memory, any feedback, a favorite recipe to share, anything at all, let us know at . We're always listening. **Try Basic Memory free for 7 days at [basicmemory.com](https://app.basicmemory.com/auth/signup){rel=""nofollow""}** # Yes, We Call It BM. No, the Logo Isn't Shaped Like One. Lately, I keep thinking back on a VelvetShark piece that made the rounds last year. One with a title that says it all: ["Why do AI logos look like buttholes?"](https://velvetshark.com/ai-company-logos-that-look-like-buttholes){rel=""nofollow""} The surface argument is the joke, but there's more to it. But to linger on the rim of the real argument for a moment, AI logos are always a circle, a soft gradient, an opening in the middle, maybe something radiating out from the center. Radek Sienkiewicz (aka VelvetShark) singles out Claude as the clearest offender, with a side-by-side comparison of the Anthropic logo and Kurt Vonnegut's illustration of an asshole from the novel *Breakfast of Champions*. They're pretty much identical. So it goes. (IYKYK.) But the resemblance isn't the interesting part. The interesting part is why it keeps happening. His real point, past all the jokes, is about sameness: these logos converge because the thinking behind them converges. Design by committee. Play it safe. Make it feel "advanced but approachable." Nobody in the room wants to be the one weird logo, so everyone ends up as the same reassuring gradient blob. Then the industry decides that blob is what serious AI is supposed to look like. At Basic Memory, we have opinions about this, partly because we're the company everyone calls "BM." But our vintage disk logo didn't come from a committee meeting, and our name didn't emerge from a branding exercise. It came out of a Turing machine. ## Where the name actually comes from Our parent company is Basic Machines, and the name is lifted straight out of an old college textbook of Paul's: Lewis and Papadimitriou's *Elements of the Theory of Computation*, from the chapter on Turing machines. There's a section in there called "The Basic Machines." It introduces the two most trivial devices you can imagine: one that writes a single symbol, and one that moves the tape head one square. That is the entire toolkit. The rest of the chapter shows you how to wire those two basic machines together into something that can actually do something, like multiplying two numbers. Basic parts, combined, make complex things. That's the whole idea. ## The sameness isn't skin-deep The sameness VelvetShark is mocking on the outside is the same sameness happening on the inside. Nearly every AI company is building the same kind of memory: a proprietary, opaque store you can't open, can't read, can't edit, and definitely can't take with you when you leave. The logos converged because the architecture converged. Look like a platform. Build the monolith. Keep the user's knowledge somewhere the user can't quite reach so they couldn't leave you even if they tried. We went the other way, deliberately, at every layer. Our logo is a floppy disk. Square, hard-edged. (Worth noting that VelvetShark's own advice for escaping the blob is to "embrace sharp angles.") And our memory is just Markdown files. Plain text. Yours. You can read every word your AI wrote, edit it however you like from anywhere you want, and walk out with all of it whenever you feel like it. There is no blob. And it still does the same job as the monoliths, but it does it better. When your AI needs something, Basic Memory finds it. Semantic search across your notes, plus the links between them that turn a pile of files into a graph. You just also happen to be able to open, read, and edit every one of those files yourself. It's as transparent as possible. ## The building blocks are simple by design A few pages after "The Basic Machines," the authors ask the obvious question: what if you gave the machine more? More tapes, more heads, a big two-dimensional surface to work on. Surely a fancier machine can do more than a basic one. The surprising answer is no. Every one of those souped-up machines can be perfectly simulated by the plain, basic one. The extra machinery buys you nothing. That's the whole philosophy. You don't need elaborate, proprietary memory systems to give an AI a good memory. The simple, boring version made of files you own already does everything the complicated version does. Because Basic Memory at scale is complex memory without the bullshit. --- Every AI company's memory looks the same because it's built the same way. Ours doesn't, because it isn't. If you want a memory for your AI that's actually yours — readable, editable, portable, plain — that's the entire idea, and you can [read more about why we built it this way](https://basicmemory.com/blog/everyones-building-memory) or just [try it](https://basicmemory.com). Your knowledge should be yours. Even the logo agrees. # Acceptable Use Policy **Last updated, effective:** June 16, 2026 This Acceptable Use Policy explains how Basic Memory Cloud may be used, what is not allowed, and what default usage limits apply. It is part of our [Terms of Service](https://basicmemory.com/terms). We want Basic Memory to support serious knowledge work, including collaboration with AI agents. We also need to keep the service reliable and prevent one customer from creating noisy-neighbor problems for others. ## Normal Use Basic Memory Cloud is designed for: - Personal and team knowledge management - Research, writing, documentation, and project memory - Human collaboration inside an Organization - AI assistants, agents, scripts, and integrations that act on behalf of licensed users - Ad hoc search, reading, editing, and syncing of knowledge across projects Normal use is welcome even when it is heavy. Large note collections, active workspaces, and frequent AI-assisted work are expected. ## Default Resource Limits Unless your plan, checkout flow, or written agreement says otherwise, these default limits apply to Basic Memory Cloud Organizations: - **Notes:** 50,000 notes per paid human seat. - **Content updates:** 1,000 content-changing operations per paid human seat per day. Content-changing operations include creating, editing, deleting, importing, moving, or syncing content that changes the hosted Organization workspace. Ordinary reads, searches, context lookups, and browsing are not counted as content updates, though they remain subject to reasonable rate limits. These limits are intended to cover normal human and team use, including reasonable agent-assisted workflows. They are not intended to turn human seats into a way to run high-volume product infrastructure or a large autonomous agent fleet. ## Agents and Automation Agents, scripts, service accounts, and integrations are allowed when they operate on behalf of licensed human users and stay within normal use. You are responsible for automated activity that runs under your account, API keys, credentials, integrations, or Organization. That includes activity initiated by AI agents. We may rate-limit, throttle, pause, or require a different plan for automated activity that: - Runs continuously or at high volume - Creates large amounts of content without human review - Produces sustained load disproportionate to the number of licensed users - Uses Basic Memory Cloud as a hosted memory backend for another product or service - Provides memory infrastructure for many agents, projects, customers, or end users outside normal Organization collaboration ## Agent Fleet and Infrastructure Use We want to support agentic fleets and cloud memory infrastructure as a real use case. It needs different commercial and operational terms than ordinary human seats. If you want to use Basic Memory Cloud as a memory layer for many autonomous agents, many projects, many customer-facing workflows, or a product you operate for others, contact us at . We can set written limits, pricing, support expectations, and operational safeguards for that use. Agent infrastructure plans may use credits or metered usage events rather than ordinary per-seat limits. Depending on the use case, the plan may meter content updates, automated runs, API activity, storage, bandwidth, active projects, active agents, or another agreed usage unit. Plans may include prepaid credits, included monthly credits, overage pricing, budget caps, rate limits, dedicated infrastructure, custom deployment, enterprise controls, or on-prem deployment. Without a separate written agreement or authorization under the [Partner Terms](https://basicmemory.com/partner-terms) and applicable Commercial Terms, Basic Memory Cloud standard plans may not be used as the primary hosted memory infrastructure for a commercial product, multi-tenant application, large autonomous agent fleet, or resale service. ## Prohibited Uses You may not use Basic Memory services to: - Violate the law or the rights of others - Store, process, or share illegal content - Harass, abuse, threaten, or exploit people - Send spam or operate unsolicited messaging systems - Distribute malware, phishing, credential theft, or other harmful code - Attempt unauthorized access to systems, accounts, data, or networks - Interfere with, scan, overload, attack, or disrupt the service - Evade rate limits, usage limits, billing controls, or security controls - Share one seat or account among multiple people - Use automated systems to create excessive load or degrade service for others - Resell Basic Memory Cloud access or provide it as a hosted service to others without written permission or authorization under the [Partner Terms](https://basicmemory.com/partner-terms) and applicable Commercial Terms - Use Basic Memory Cloud as a bulk file host, backup dump, scraping target, or general-purpose database unrelated to knowledge work ## Public Sharing If your Organization uses public links, you are responsible for the content made public through those links. Do not use public sharing for illegal content, harassment, spam, phishing, malware, rights violations, or content that violates this policy. We may disable public links that violate this policy or create risk for the service. ## Enforcement We try to be practical. For ordinary overages or accidental automation mistakes, we may contact the Organization Owner, apply throttling, or ask you to adjust usage. For serious abuse, security risk, illegal activity, payment abuse, or activity that harms other users or the service, we may immediately restrict, suspend, or terminate access. ## Changes to This Policy We may update this policy as the service evolves. Changes are effective when posted unless we specify a later effective date. If a change materially affects existing customers, we may provide additional notice by email, in-product notice, or another reasonable method. ## Contact Questions about this policy or higher-volume use? Contact . # Partner Program Policy **Last updated, effective:** June 16, 2026 This Partner Program Policy applies to Basic Memory partners, managed service providers, resellers, consultants, implementation partners, and similar service providers who market, resell, implement, administer, or support Basic Memory as an authorized partner. This policy is part of our [Partner Terms](https://basicmemory.com/partner-terms) and supplements our [Terms of Service](https://basicmemory.com/terms), [Acceptable Use Policy](https://basicmemory.com/acceptable-use), and [Privacy Policy](https://basicmemory.com/privacy). ## Core Standards Partners must be honest, accurate, transparent, and professional. When you market, resell, implement, administer, or support Basic Memory: - Make truthful claims based on real product capabilities and your actual experience. - Keep sales, support, implementation, and customer-facing materials current. - Clearly distinguish your business from Basic Memory. - Do not overstate results, security, compliance status, uptime, support, integrations, roadmap commitments, or AI outcomes. - Do not make legal, medical, financial, compliance, productivity, or business-result guarantees. - Do not use fear, pressure, harassment, deception, spam, impersonation, or dark patterns. - Respect intellectual property, privacy, confidentiality, and customer choice. ## Relationship and Authority You must accurately describe your relationship with Basic Memory and with each customer you manage. - Identify your business as the provider of your professional services, implementation work, support, customer billing, and customer communications. - Do not claim to be Basic Memory, an employee of Basic Memory, an exclusive representative, or a person with authority to bind Basic Memory. - Do not make warranties, guarantees, refunds, credits, service commitments, security commitments, data commitments, pricing promises, or legal commitments on behalf of Basic Memory. - Do not imply that Basic Memory endorses your services, customers, pricing, advice, implementation, or marketing claims unless Basic Memory has approved that statement in writing. - Do not create, claim, administer, support, bill, configure, or access a Managed Customer workspace unless you have authorization from that customer. ## Marketing and Brand Use You may use Basic Memory names, logos, screenshots, product descriptions, and other brand assets only as authorized by Basic Memory and only to describe your authorized partner relationship accurately. You may not: - Modify Basic Memory logos, marks, or screenshots in a misleading way. - Use Basic Memory marks in domain names, social handles, app names, business names, ad account names, search keywords, or source identifiers in a way that creates confusion. - Copy, frame, clone, or mirror Basic Memory websites, product pages, checkout pages, documentation, or app screens in a way that suggests impersonation. - Use Basic Memory marks with illegal, harmful, deceptive, harassing, hateful, adult, malware, spyware, infringing, or brand-unsafe content. - Offer Basic Memory coupons, discounts, promotions, contests, giveaways, free trials, migration offers, implementation credits, or other incentives unless Basic Memory expressly authorizes them in writing or through the partner portal. You may offer your own professional services, implementation packages, consulting, training, or support, but you must make clear that those services are provided by you and not by Basic Memory. If we ask you to stop or change a brand use, you must do so promptly. ## Customer Communications and Support You are responsible for your own customer communications and support obligations. You must: - Make clear whether a communication comes from you or from Basic Memory. - Accurately describe what Basic Memory provides and what you provide separately. - Maintain appropriate support channels for your Managed Customers. - Promptly communicate material support, billing, onboarding, access, or offboarding information to Managed Customers when you are responsible for that relationship. - Avoid customer communications that are misleading, coercive, discriminatory, abusive, or likely to harm customer trust in Basic Memory. ## Marketing Compliance You are responsible for your own marketing and outreach. You must comply with all applicable advertising, telemarketing, email, text message, privacy, consumer protection, platform, and industry rules. Without limiting that obligation: - Marketing emails must identify you as the sender, use accurate headers and subject lines, include required physical address information, and provide an opt-out mechanism you honor promptly. - Calls, texts, automated messages, and AI-assisted outreach must comply with consent, recordkeeping, and sender-identification rules. - You may not send spam, scraped-list outreach, unsolicited mass messages, or deceptive lead generation. - You must maintain any required privacy policy and describe how you collect, use, share, and protect personal information. - You must keep records needed to show consent, opt-outs, and compliance when law requires it. - You must promptly honor unsubscribe, deletion, access, correction, and similar requests that apply to data you control. All partner marketing must identify Partner, not Basic Memory, as the sender or speaker unless Basic Memory expressly approves otherwise in writing. ## Customer and Prospect Data You are responsible for personal information you collect from prospects, customers, Managed Customers, Customer End Users, or event participants. You must: - Collect and use personal information lawfully, fairly, and transparently. - Use personal information only for authorized partner activities and customer services. - Protect personal information with reasonable safeguards. - Avoid selling, renting, or misusing personal information received through partner activity. - Honor privacy rights and opt-outs that apply to data you control. - Notify Basic Memory promptly if you believe data connected to Basic Memory services or partner activity has been accessed, disclosed, or used without authorization. If Basic Memory shares personal information with you under a separate data processing agreement, that agreement controls for the covered processing. ## Prohibited Conduct You may not market, resell, implement, support, administer, or use Basic Memory through: - Illegal, fraudulent, deceptive, abusive, discriminatory, hateful, harassing, or exploitative activity. - Spam, phishing, malware, spyware, credential harvesting, scraping abuse, or unauthorized tracking. - False claims about Basic Memory, competitors, customers, AI outcomes, security, compliance, integrations, or roadmap. - Content or placements that could reasonably harm Basic Memory's reputation or customer trust. - Sanctioned persons, comprehensively sanctioned jurisdictions, prohibited end uses, or export-control violations. - Unauthorized lead brokers, ad networks, contractors, or other third parties using your partner status or customer access. - Infringing content, copied sales pages, misleading comparison pages, or materials that violate platform rules. ## Complaints, Monitoring, and Cooperation You must notify us promptly at if you receive a legal demand, regulator inquiry, platform complaint, customer complaint, privacy request, security report, or intellectual property complaint related to Basic Memory partner activity. We may review partner websites, landing pages, ads, emails, social posts, events, scripts, demos, support materials, customer communications, and similar channels for compliance with this policy. You must cooperate with reasonable compliance reviews, correction requests, and investigations. ## Consequences Violating this Partner Program Policy is a violation of the Partner Terms. We may take any action we consider appropriate, including: - Warning you or requiring corrective action. - Requiring edits, takedowns, retractions, notices, or customer corrections. - Suspending partner portal access, partner APIs, partner-only tools, or brand permissions. - Suspending or terminating the Partner Account or partner relationship. - Disabling Managed Customer onboarding or customer access where needed to protect customers or the service. We may act immediately when we believe there is legal, security, privacy, customer, brand, payment, or operational risk. ## Changes We may update this Partner Program Policy from time to time. Changes are effective when posted unless we specify a later effective date. For material changes, we may provide additional notice by email, partner portal notice, in-product notice, or another reasonable method. Continuing partner activity after changes become effective means you accept the updated policy. ## Contact Questions about this policy? Contact . # Partner Terms **Last updated, effective:** June 16, 2026 These Partner Terms apply when a person or business joins, claims, accesses, or uses a Basic Memory partner account, partner portal, partner API, partner CLI, managed service provider account, reseller arrangement, implementation partner arrangement, consulting partner arrangement, or other partner program offered by Basic Memory LLC. These Partner Terms supplement our [Terms of Service](https://basicmemory.com/terms), [Acceptable Use Policy](https://basicmemory.com/acceptable-use), [Privacy Policy](https://basicmemory.com/privacy), and [Partner Program Policy](https://basicmemory.com/partner-program-policy). If these Partner Terms conflict with the general Terms of Service for partner-specific activity, these Partner Terms control. If we sign a separate written agreement with you, that written agreement controls over these Partner Terms for the conflicting subject matter. ## Acceptance By claiming a partner invitation, accessing the partner portal, using a partner API or CLI, creating or managing customer workspaces, purchasing a partner subscription, using partner billing terms, promoting Basic Memory as an authorized partner, or otherwise participating in a Basic Memory partner program, you agree to these Partner Terms. If you accept these Partner Terms on behalf of a company or other organization, you represent that you have authority to bind that organization. In that case, "Partner," "you," and "your" refer to that organization. If you do not agree to these Partner Terms, do not claim the partner account or use partner features. ## Definitions - **Partner** means a person or business authorized by Basic Memory to participate in a partner, MSP, reseller, implementation, consulting, or similar program. - **Partner Account** means the Basic Memory partner account, partner portal access, partner API access, partner CLI access, partner billing relationship, and related partner records. - **Partner Owner** means the person who claims or administers the Partner Account with owner-level authority. - **Partner Staff** means employees, contractors, representatives, support personnel, billing users, or other users invited into the Partner Account. - **Managed Customer** means a customer, client, tenant, organization, or workspace that Partner manages, administers, supports, bills, implements, or services through Basic Memory Cloud. - **Customer End User** means an individual user of a Managed Customer workspace. - **Commercial Terms** means the pricing, setup fees, committed seats, overage settings, overage rates, usage units, payment cadence, credits, checkout terms, or other economic terms shown in the partner portal, billing flow, order form, invoice, or separate written agreement. - **Partner Materials** means Basic Memory names, logos, trademarks, product screenshots, sales collateral, documentation, code samples, templates, and other materials we make available for partner use. ## Partner Account Authority The Partner Owner is responsible for the Partner Account and for all Partner Staff. You are responsible for: - Keeping Partner Account credentials, API keys, CLI tokens, and billing access secure. - Ensuring Partner Staff use the partner portal, APIs, CLI, customer access, and billing tools only as authorized. - Removing Partner Staff promptly when access is no longer needed. - Making sure Partner Staff comply with these Partner Terms, the Terms of Service, the Acceptable Use Policy, the Privacy Policy, and the Partner Program Policy. - All activity that occurs through your Partner Account, including activity by Partner Staff, contractors, agents, integrations, scripts, and automated tools. We may suspend or restrict a Partner Account if we reasonably believe account credentials are compromised, access is unauthorized, payment is overdue, a Managed Customer is at risk, or the Partner Account is being used in violation of these Partner Terms. ## Independent Relationship Partner is an independent contractor. These Partner Terms do not create an employment, agency, franchise, joint venture, fiduciary, exclusive, or partnership relationship between Partner and Basic Memory. Unless we expressly agree in writing, Partner may not: - Bind Basic Memory to any contract or obligation. - Make warranties, guarantees, refunds, credits, service commitments, security commitments, data commitments, or pricing promises on behalf of Basic Memory. - Represent that Partner is an employee, agent, legal representative, or exclusive partner of Basic Memory. - Use Basic Memory as a business opportunity, franchise, "business in a box," or income-guarantee program. Basic Memory may work with other partners, customers, consultants, resellers, and service providers. Partner may work with other products and services, subject to confidentiality and other obligations in these Partner Terms. ## Managed Customers Partner is responsible for its relationship with each Managed Customer. Partner acts as the Managed Customer's authorized administrator, service provider, or agent for partner-managed Basic Memory workspaces. Partner is not Basic Memory's agent and may not bind Basic Memory to commitments with Managed Customers. Unless we agree otherwise in writing: - Partner is responsible for obtaining and maintaining authorization from each Managed Customer before creating, managing, accessing, supporting, administering, billing, or configuring that customer's Basic Memory workspace. - By creating, claiming, connecting, or managing a Managed Customer workspace, Partner certifies that Partner has authority from the Managed Customer to administer the workspace and access workspace information as needed to provide partner services. - Partner is responsible for its own customer agreements, customer invoices, payment collection, taxes, refunds, support obligations, onboarding promises, implementation work, and customer communications. - Partner must ensure Managed Customers and Customer End Users comply with the Terms of Service and Acceptable Use Policy. - Partner may not misrepresent Basic Memory's role in the Partner's customer relationship. - Partner may not grant Basic Memory access rights, customer obligations, or customer-facing commitments that Basic Memory has not accepted in writing. - Partner is responsible for offboarding Managed Customers that leave Partner's service. Partner-facing billing reports, customer billing statements, CSV exports, usage rows, and similar partner tools are operational records to help Partner manage and rebill customers. Unless we say otherwise in writing, they are not official invoices from Basic Memory to Managed Customers. ## Customer Access and Data Partner may receive access to Managed Customer workspaces, account information, usage information, billing labels, seat information, SSO configuration, support contact information, and other data as needed to provide partner services. Partner must: - Access Managed Customer data only for authorized partner services. - Make sure Partner's authorization covers the specific administration, support, SSO configuration, billing, and content access Partner performs. - Use least-privilege access and appropriate administrative controls. - Protect customer data using reasonable administrative, technical, and organizational safeguards. - Maintain appropriate confidentiality obligations with Partner Staff and contractors. - Promptly notify Basic Memory of any suspected unauthorized access, credential compromise, data incident, or security incident involving Basic Memory services or Managed Customer data. - Comply with applicable privacy, data protection, consumer protection, security, export control, sanctions, anti-corruption, and professional services laws. Partner is responsible for its own privacy notices and legal basis for any personal information Partner collects directly from prospects, Managed Customers, or Customer End Users. If Partner processes personal information for a Managed Customer, Partner is responsible for its role under applicable privacy laws. Partner must enter into Basic Memory's data processing agreement or another written data protection agreement before Partner manages customer workspaces or accesses customer content, unless Basic Memory agrees in writing that a separate data processing agreement is not required for the applicable partner activity. Any separate data processing agreement, business associate agreement, security addendum, or customer-specific privacy agreement must be signed by Basic Memory to bind Basic Memory. If signed, that agreement controls for the covered processing. ## Commercial Terms and Partner Billing Partner Commercial Terms may be shown in the partner portal, checkout flow, billing portal, product configuration, order form, invoice, or separate written agreement. Commercial Terms may include setup fees, committed seats, base price, overage price, billing cadence, usage units, credits, caps, payment timing, support terms, or custom commitments. Unless your Commercial Terms say otherwise: - Partner is billed by Basic Memory for the Partner Account, not by each Managed Customer. - Any setup fee shown in the Commercial Terms is a one-time, non-creditable, non-refundable fee due before or during partner onboarding unless the Commercial Terms say otherwise or applicable law requires otherwise. - Partner billing is monthly in arrears for fees, committed seats, metered usage, overages, and other charges accrued during the prior billing period. - Partner authorizes Basic Memory and its payment processor to charge or invoice Partner for recurring fees, committed seats, metered usage, overage, credits, taxes, and other charges described in the Commercial Terms. - Partner is responsible for all taxes, duties, assessments, and government charges associated with Partner's purchases, resale, customer billing, and services, except taxes based on Basic Memory's net income. - Payment failure, chargebacks, fraud risk, or overdue amounts may result in suspension or termination of the Partner Account or Managed Customer access. - Where available, Partner may choose overage behavior in the partner dashboard, including just-in-time provisioning that permits billable increases or a hard stop that blocks provisioning or use beyond selected limits. - Adding seats, adding Managed Customers, enabling just-in-time provisioning or overage, or increasing commitment automatically increases current or future charges according to the Commercial Terms. - Commitment decreases, refunds, credits, and mid-cycle commercial changes require Basic Memory support or manual amendment unless available self-serve in the partner portal. Partner remains responsible for amounts accrued before suspension, cancellation, or termination. ## Marketing, Brand, and Public Statements Partner may use Partner Materials only as permitted by Basic Memory and only to accurately describe Partner's authorized relationship with Basic Memory. Partner must follow the [Partner Program Policy](https://basicmemory.com/partner-program-policy) for marketing, sales, brand use, privacy, compliance, customer communications, and prohibited conduct. Unless we approve it in writing, Partner may not: - Use Basic Memory trademarks in domain names, social handles, app names, company names, ads, or source identifiers in a way that creates confusion. - Modify Basic Memory logos or brand assets. - Copy or frame Basic Memory websites in a way that suggests impersonation or official operation by Basic Memory. - Issue press releases, public announcements, case studies, or customer references describing the partner relationship. - Represent that Basic Memory endorses Partner's services, customers, pricing, implementation, claims, or advice. - Offer coupons, discounts, promotions, contests, giveaways, or free trials on behalf of Basic Memory. Any goodwill from Partner's permitted use of Basic Memory marks belongs to Basic Memory. ## Confidentiality Partner may receive non-public Basic Memory business, technical, financial, security, roadmap, pricing, customer, prospect, product, operational, or partner program information. Partner may use that confidential information only to perform authorized partner activities. Partner must not disclose Basic Memory confidential information except to Partner Staff or contractors who need it for authorized partner activities and are bound by confidentiality obligations at least as protective as these Partner Terms. When the partner relationship ends, Partner must stop using and return or delete Basic Memory confidential information on request, except that Partner may retain copies required by law or ordinary backup systems if they remain protected. Confidentiality obligations survive termination. ## Compliance Partner is responsible for compliance with laws and regulations that apply to Partner's business, marketing, services, customer relationships, data handling, and resale activity. Partner may not use, market, resell, export, re-export, or provide Basic Memory services in violation of sanctions, export controls, anti-corruption laws, privacy laws, consumer protection laws, telemarketing laws, advertising laws, or intellectual property laws. Partner may not promote or provide Basic Memory services to sanctioned persons, comprehensively sanctioned jurisdictions, or prohibited end uses. ## Term, Suspension, and Termination These Partner Terms begin when Partner first accepts them or participates in a partner program and continue until the partner relationship ends. Either party may end the partner relationship for convenience by providing written notice unless a separate written agreement says otherwise. We may suspend or terminate Partner's access immediately if Partner: - Breaches these Partner Terms, the Terms of Service, the Acceptable Use Policy, the Privacy Policy, the Partner Program Policy, or Commercial Terms. - Fails to pay amounts due. - Creates security, privacy, compliance, customer, brand, fraud, abuse, or operational risk. - Misuses Basic Memory marks or confidential information. - Makes unauthorized commitments on Basic Memory's behalf. - Uses Basic Memory services for illegal, abusive, misleading, or unauthorized activity. Upon termination, Partner must stop using partner access, Partner Materials, Basic Memory marks, confidential information, and partner-only APIs or CLI tools. We may disable Partner Staff access and restrict Managed Customer administration. ## Customer Transition and Offboarding When a Partner Account is suspended or terminated, Basic Memory may, but is not obligated to, help transition Managed Customers to direct Basic Memory accounts, another partner, exports, or another reasonable offboarding path. Partner remains responsible for its customer communications, customer contracts, outstanding customer obligations, and any amounts owed to Basic Memory. Basic Memory may communicate with Managed Customers as needed to protect the service, comply with law, preserve data, prevent harm, or support offboarding. If a Managed Customer leaves Partner's service, Partner is responsible for offboarding that customer. For 90 days after Partner notifies Basic Memory in writing that a Managed Customer has left Partner's service or should be offboarded, Basic Memory will not knowingly convert that Managed Customer to a direct paid Basic Memory account for the same workspace without Partner's approval. This restriction does not limit Basic Memory's ability to communicate with Managed Customers or take action needed to protect the service, comply with law, preserve or export data, prevent harm, address security or payment risk, or support reasonable offboarding. Customer data retention, deletion, export, and backup behavior remains governed by the Terms of Service, Privacy Policy, applicable Commercial Terms, and any separate written agreement. ## Indemnification In addition to the indemnification obligations in the Terms of Service, Partner agrees to indemnify and hold harmless Basic Memory LLC, its officers, directors, employees, contractors, and agents from claims, damages, fines, losses, liabilities, and expenses, including legal fees, arising from: - Partner's breach of these Partner Terms, the Partner Program Policy, Commercial Terms, or applicable law. - Partner's services, marketing, implementation, support, resale, or customer billing. - Partner's relationship with Managed Customers or Customer End Users. - Partner's unauthorized commitments, representations, warranties, guarantees, discounts, refunds, or service promises. - Partner's collection, use, disclosure, transfer, or protection of personal information. - Partner's misuse of Basic Memory marks, Partner Materials, confidential information, APIs, CLI tools, or partner portal access. - Activity by Partner Staff, contractors, agents, representatives, scripts, integrations, or automated tools. ## Partner Limitation of Liability To the maximum extent permitted by law, Basic Memory's total aggregate liability for claims arising out of or related to these Partner Terms, Partner Accounts, Managed Customers, Partner Staff, partner billing, Commercial Terms, partner APIs, partner CLI tools, or partner-managed workspaces will not exceed the amounts Partner paid to Basic Memory under the applicable Partner Account during the 12 months before the event giving rise to the claim. This partner-specific cap replaces the general Terms of Service monetary floor for partner-specific claims. Nothing in this section increases Basic Memory's liability beyond the limitations, exclusions, and disclaimers in the Terms of Service. This section does not limit Partner's payment obligations, tax obligations, indemnification obligations, confidentiality obligations, or liability for unauthorized access, misuse of Basic Memory services, or misuse of Managed Customer data. ## Changes We may update these Partner Terms from time to time. Changes are effective when posted unless we specify a later effective date. For material changes, we may provide additional notice by email, in-product notice, partner portal notice, or another reasonable method. Partner's continued participation in a partner program after changes become effective means Partner accepts the updated Partner Terms. ## Survival The sections covering Customer Access and Data, Commercial Terms and Partner Billing, Marketing and Brand, Confidentiality, Compliance, Customer Transition and Offboarding, Indemnification, Partner Limitation of Liability, Changes, and any payment obligations survive termination to the extent needed to give them effect. ## Contact Questions about these Partner Terms? Contact . # Privacy Policy **Last updated, effective:** June 30, 2026 ## Our Privacy Commitment At Basic Memory, we believe your data belongs to you. This policy explains what information we collect, how we use it, and your rights regarding your data. ## What Basic Memory Is Basic Memory offers two ways to use our service: - **Open-source software** that runs locally on your machine - **Basic Memory Cloud** - a hosted service for syncing across devices ## Information We Collect ### For Basic Memory Cloud Users When you use Basic Memory Cloud, we collect: #### Account Information - Email address (for authentication and communication) - Name (optional, for account management) - Authentication credentials (managed through WorkOS) - Subscription and billing information (processed by Polar.sh) #### Your Knowledge Data - Notes and knowledge base content you create - File attachments and metadata - Knowledge graph connections - Usage patterns for service operation #### Technical Information - Device information (browser, OS) - IP address and general location - Log data (access times, features used) - API usage and performance metrics #### Usage Analytics Unlike the anonymous telemetry in our open-source software, Cloud usage data is tied to your account: - Feature usage (which tools and commands you use) - Performance metrics for service optimization - Error tracking for debugging and support This account-linked data helps us provide better support and improve your experience. #### Partner-Managed Accounts If your organization or workspace is managed by a partner, MSP, reseller, consultant, or similar service provider authorized by you or your organization, we may collect and process partner-management information such as: - Partner account and partner staff contact information - Managed customer names, workspace identifiers, billing labels, external customer identifiers, and support contacts - Seat assignments, seat caps, usage records, billing summaries, payment status, and customer billing statement rows - SSO domains, SSO configuration status, and administrator contact details - Audit logs and support records related to partner access and customer administration Partner staff may be able to access, configure, support, or administer your workspace as your organization's authorized administrator, service provider, or agent according to the permissions granted through the partner relationship. The partner is responsible for its own privacy notices, customer contracts, support practices, and use of personal information it collects directly from you. ### For Website Visitors With your consent, this website (basicmemory.com) collects analytics: - Page views and navigation patterns - Click events on links and calls to action - General location (country/region) - Device and browser type - Referral sources - Session replay and interaction recordings so we can understand confusing flows, broken pages, and product interest ### For Open Source Software Users When you use Basic Memory software locally: - **Your knowledge stays local** - Notes and content never leave your device - **No accounts required** - Use it completely offline - **Anonymous telemetry** - We collect minimal, anonymous usage statistics (opt-out available) #### Telemetry (Opt-Out) Basic Memory collects anonymous usage statistics to help improve the software. This follows the [Homebrew model](https://docs.brew.sh/Analytics){rel=""nofollow""} - on by default with easy opt-out. **What we collect:** - App version, Python version, OS, architecture - Feature usage (which tools are used) - Error types (sanitized - no file paths or personal data) **What we NEVER collect:** - Note content, file names, or paths - Personal information or IP addresses **To opt out:** Run `basic-memory telemetry disable` or set `BASIC_MEMORY_TELEMETRY_ENABLED=false` See our [Telemetry page](https://basicmemory.com/telemetry) for complete details. ## How We Use Your Information ### To Provide the Service - Store and sync your knowledge base across devices - Process your requests and commands - Enable integrations with AI assistants - Provide customer support - Enable authorized partners acting as customer administrators, service providers, or agents to administer, support, bill, and manage partner-managed customer workspaces ### To Improve Our Service - Analyze usage patterns to improve features - Debug technical issues - Optimize performance - Develop new capabilities ### To Communicate With You - Send service updates and notifications - Respond to support requests - Provide important account information - Share product updates (you can opt out) ### For Legal and Security - Comply with legal obligations - Prevent fraud and abuse - Protect user security - Enforce our Terms of Service - Enforce our Partner Terms and partner program requirements ## How We Protect Your Data ### Cloud Data Security - **Data encryption** - Your data is encrypted at rest and in transit - **Your private cloud** - Each customer gets an isolated instance - **Secure infrastructure** - Industry-standard security practices - **Regular backups** - Automatic backups for data protection - **Access controls** - Strict internal access limitations ### What We DON'T Do - **We don't sell your data** - Never have, never will - **We don't share with advertisers** - Your data isn't for marketing - **We don't train AI models** - Your content stays private - **We don't read your data** - Except when necessary for support requests you initiate ## Partner-Managed Workspaces When a workspace is partner-managed, the partner may act as your organization's authorized administrator, service provider, reseller, consultant, or managed service provider. Depending on the configuration and permissions, partner staff may be able to: - Invite or remove users - Assign seats and manage seat caps - Configure SSO or customer settings - View billing and usage summaries for rebilling or support - Access workspace content when authorized to provide support or administration - Receive operational notices about the managed workspace We share partner-management information with the relevant partner only as needed to provide, secure, bill, support, and administer the partner-managed service. We rely on the partner to certify that it is authorized by your organization before it creates, claims, administers, or accesses a partner-managed workspace. We do not authorize partners to use your content or personal information for unrelated advertising, resale, or profiling. If your workspace is managed by a partner and you have questions about that partner's privacy practices, customer contract, invoices, support commitments, or access to your workspace, contact the partner directly. You can also contact Basic Memory at . ## Data Retention ### Active Accounts - Data retained as long as your account is active - You can delete specific content anytime ### After Cancellation - Data retained for 30 days (in case you change your mind) - Automatically deleted after 30 days - Request immediate deletion by contacting us ### Backups - May persist in backups for up to 90 days - Securely deleted from backups on our regular schedule ## Third-Party Services ### Authentication (WorkOS) - Handles user authentication securely - Subject to their privacy policy - We don't store your passwords ### Payments (Polar.sh) - Processes subscription payments - We don't store your payment card details - Subject to their privacy policy ### AI Assistants When you connect to AI services (Claude, ChatGPT, Gemini): - **Direct connection** - Your data goes to them for processing - **Their policies apply** - Review their privacy policies - **You control the connection** - Disconnect anytime ### Analytics (Umami and Rybbit) - Minimal website and app analytics for improvement - Website analytics are consent-based and include page views, click events, navigation patterns, referral sources, general location, device/browser information, and session replay - Cloud app analytics may be linked to your account or user profile so we can debug support issues, understand cancellation behavior, and improve the product - Session replay may record page layout and interactions; app replay is configured to mask text and form inputs and block images so note content and embedded note media are not intentionally captured - We do not use analytics data for advertising, data sales, or unrelated profiling - Subject to [Umami's privacy policy](https://umami.is/privacy){rel=""nofollow""} and [Rybbit's privacy policy](https://rybbit.com/privacy){rel=""nofollow""} ## Your Rights and Choices ### Access Your Data - Download your entire knowledge base anytime - Export in standard Markdown format - Request a copy of your account data ### Modify Your Data - Edit or delete content through the service - Update your account information - Manage your subscription ### Delete Your Data - Delete your account and all data - Request immediate data deletion - Data removed within 30 days (backups within 90 days) ### Opt Out - Unsubscribe from marketing emails - Manage or disable website analytics cookies from the Cookie Preferences link in the site footer - [Disable telemetry](https://basicmemory.com/telemetry) in the open source software - Close your account ### Data Portability - Export your data in standard formats - Take it to another service - No lock-in or proprietary formats ## International Data Transfers Basic Memory Cloud servers are located in the United States. By using our service, you consent to your data being processed in the US. We take appropriate measures to protect your data regardless of where it's processed. ## Children's Privacy Basic Memory Cloud is not directed at children under 18. We don't knowingly collect information from children. If you believe a child has provided us with personal information, please contact us and we'll delete it. For the open-source software: Parents have full control since data stays local. ## California Privacy Rights California residents have additional rights under CCPA: - **Right to know** - What personal information we collect - **Right to delete** - Request deletion of your data - **Right to opt-out** - Of data sales (we don't sell data) - **Right to non-discrimination** - Same service regardless of privacy choices Contact us to exercise these rights. ## Changes to This Policy We may update this policy to reflect changes in our practices or for legal reasons. Changes are posted on this page and reflected in the "Last updated" date. Changes are effective when posted unless we specify a later effective date. For material changes, we may provide additional notice by email, in-product notice, or another reasonable method. ## Beta Program Privacy If you're in our beta program: - **Increased data collection** - For debugging and improvement - **Feedback usage** - Your feedback helps shape the product - **Early access** - You get new features first - **Same protections** - All privacy commitments still apply ## Contact Us Questions or concerns about privacy? **Privacy Inquiries:** **General Support:** **GitHub:** {rel=""nofollow""} **Address:** Basic Memory LLC, Austin, Texas ## Our Philosophy At Basic Memory, we believe: - **Your data belongs to you** - Not to us or big tech companies - **Privacy by design** - Built into our architecture - **Transparency** - Clear policies and open source code - **User control** - You decide what happens with your data - **Minimal collection** - We only collect what's necessary --- *Privacy isn't a feature to us—it's a fundamental principle.* # Telemetry **Last updated:** December 27, 2025 ## Our Approach Basic Memory collects anonymous usage statistics to help improve the software. We follow the [Homebrew model](https://docs.brew.sh/Analytics){rel=""nofollow""} - telemetry is **on by default** with **easy opt-out**. We believe in transparency. This page explains exactly what we collect, why, and how to opt out if you prefer. > **Note for Cloud Users:** This page describes telemetry for the open-source software. If you use Basic Memory Cloud, usage data is associated with your account (not anonymous) and covered by our [Privacy Policy](https://basicmemory.com/privacy). Cloud usage tracking helps us provide better support and service. ## What We Collect ### Usage Data - **App version** - Which version of Basic Memory you're using - **Python version** - Your Python runtime version - **Operating system** - macOS, Linux, or Windows - **Architecture** - CPU architecture (x86\_64, arm64, etc.) - **Feature usage** - Which MCP tools and CLI commands are used - **Error types** - Exception class names (e.g., "FileNotFoundError") ### Anonymous Identifier - A random UUID generated on first run - Stored locally at `~/.basic-memory/.install_id` - Not linked to any personal information - You can reset it anytime by deleting the file ## What We NEVER Collect - **Note content** - Your knowledge base content stays private - **File names or paths** - We sanitize error messages to remove paths - **Personal information** - No names, emails, or identifying data - **IP addresses** - Our analytics provider (OpenPanel) doesn't store IPs - **File system structure** - We don't see your directory layout - **Query content** - What you search for stays private ## Why We Collect This Understanding how Basic Memory is used helps us: - **Prioritize features** - Focus on what people actually use - **Fix bugs faster** - See which errors occur most frequently - **Improve performance** - Understand usage patterns - **Make better decisions** - Data-informed product development ## How to Opt Out ### Via CLI (Recommended) ```bash # Disable telemetry basic-memory telemetry disable # Check status basic-memory telemetry status # Re-enable if you change your mind basic-memory telemetry enable ``` ### Via Environment Variable ```bash export BASIC_MEMORY_TELEMETRY_ENABLED=false ``` Add this to your shell profile (`.bashrc`, `.zshrc`, etc.) to make it permanent. ### Via Config File Edit `~/.basic-memory/config.json`: ```json { "telemetry_enabled": false } ``` ## First-Run Notice On first use, Basic Memory displays a one-time notice informing you about telemetry. This is not a prompt - it's just information. Telemetry is already enabled unless you choose to disable it. ## Data Handling ### Storage - Data is sent to [OpenPanel](https://openpanel.dev){rel=""nofollow""}, a privacy-focused analytics platform - No data is stored locally except your install ID - Events are fire-and-forget - they don't slow down your workflow ### Retention - Aggregated data is retained for product analytics - Individual events are not personally identifiable - No correlation between events and users beyond the anonymous ID ### Security - Data is transmitted over HTTPS - API credentials are write-only (cannot read any data) - No sensitive information is ever transmitted ## Comparison with Other Tools | Tool | Telemetry Default | Opt-Out Method | | ------------ | ----------------- | -------------------- | | Basic Memory | On | CLI command | | Homebrew | On | Environment variable | | VS Code | On | Settings toggle | | npm | On | Config flag | We follow industry best practices by making telemetry: - **Transparent** - Clear documentation of what's collected - **Anonymous** - No personal data or identifying information - **Opt-out** - Easy to disable with a single command - **Non-blocking** - Never affects your workflow ## Open Source Commitment Our telemetry implementation is open source. You can review exactly what data is collected: - **Source code**: [telemetry.py on GitHub](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/telemetry.py){rel=""nofollow""} - **Tests**: [test\_telemetry.py](https://github.com/basicmachines-co/basic-memory/blob/main/tests/test_telemetry.py){rel=""nofollow""} ## Questions? If you have questions or concerns about telemetry: **Email:** **GitHub:** [Open an issue](https://github.com/basicmachines-co/basic-memory/issues){rel=""nofollow""} --- *We respect your privacy. Telemetry helps us build a better product, but we understand if you prefer not to participate.* # Terms of Service **Last updated, effective:** June 16, 2026 ## Acceptance of Terms By using this website, creating an account, joining a Basic Memory workspace, subscribing to Basic Memory Cloud, claiming or joining a partner account, using Basic Memory software, or otherwise using our services, you agree to these Terms of Service. If you do not agree, do not use the services. These terms apply to Basic Memory LLC, Basic Memory Cloud, this website, our documentation, and our open-source software where applicable. Partner accounts, managed service provider relationships, reseller activity, implementation partner activity, consulting partner activity, and other partner programs are also subject to our [Partner Terms](https://basicmemory.com/partner-terms) and [Partner Program Policy](https://basicmemory.com/partner-program-policy). ## Simple Terms Basic Memory helps people and AI assistants build persistent knowledge together. We try to keep the rules simple: - You own the content you create. - Your team workspace is its own tenant. - Seats are for individual human users. - Agents and integrations are allowed, but you are responsible for what they do. - We may set reasonable limits to keep the service reliable and prevent abuse. - Partners are responsible for their own customers, staff, marketing, billing, and authorized customer access. ## What Basic Memory Is Basic Memory is a knowledge management system for building persistent knowledge through natural conversations with AI assistants. We offer: - **Open-source software** that can run locally on your machine - **Basic Memory Cloud**, a hosted service for syncing, editing, and collaborating on knowledge - **Documentation and community resources** Our core principles: - **Local-first** - Your data can stay on your device when you use the local software. - **Open source** - Core software is available on GitHub under open licenses. - **Privacy-focused** - Cloud workspaces are isolated by tenant. - **User control** - You own your data and can export it. ## Using Basic Memory Software ### The Open-Source Software - Basic Memory software is free to download and use. - It is distributed under open-source licenses described in our GitHub repository. - You may modify and distribute it according to those licenses. - No Basic Memory Cloud account is required for the core local software. - You may use the local software entirely offline if you choose. ### This Website - You may browse our marketing site and documentation freely. - We may collect basic analytics as described in our Privacy Policy. - Some features require account creation. ## Basic Memory Cloud Service ### Service Description Basic Memory Cloud is our hosted service. It provides: - Hosted Basic Memory workspaces - Synchronization across devices - Web, mobile, and desktop access where available - Data encrypted in transit and at rest - Integration with AI assistants, agents, and other tools - Collaboration features for teams and organizations Basic Memory Cloud is organized around organization workspaces. In these terms, an **Organization** means a Basic Memory Cloud tenant with one owner, one subscription, and one or more seats. A solo user has an Organization with one seat. A team adds collaborators by buying and assigning additional seats. Each Organization is its own tenant. Organization data is not shared with any other Organization unless you or your members intentionally export it, publish it, share it, connect an integration, or otherwise direct the service to disclose it. Some Organizations may be managed by an authorized Basic Memory partner, managed service provider, reseller, consultant, or similar service provider. Partner-managed Organizations remain Basic Memory Cloud tenants, but partner access, partner responsibilities, customer administration, and partner billing are governed by the [Partner Terms](https://basicmemory.com/partner-terms) and any applicable Commercial Terms. ### Beta Program If you participate in a beta program: - **Beta status:** The service is in active development and may have bugs, limitations, or unexpected behavior. - **No guarantees:** Features may change, be removed, or not work as expected. - **Feedback:** We appreciate feedback that helps us improve. - **Data safety:** Maintain backups of critical data. - **Service changes:** We may modify features, pricing, or availability during beta. - **Early adopter benefits:** Any special pricing or benefits will be described at sign-up or checkout. ### Account Registration and Organization Accounts To use Basic Memory Cloud, you must create an account with accurate information, keep your credentials secure, and notify us of unauthorized access. You must be at least 18 years old or have parental or legal guardian consent. Any account holder may create an Organization. When you create an Organization, you are its **Owner**. ### Roles Members may have different roles within an Organization: - **Owner** - Full administrative control, including members, roles, billing, public sharing settings, Organization settings, and subscription management. The Owner is the customer of record for billing purposes. - **Editor** - Day-to-day collaboration, including creating and editing notes and projects within the Organization workspace. - **Viewer** - Read-only access to the projects and notes made available to that role. A single Basic Memory account may belong to multiple Organizations. Each Organization is independent for billing, content, access, and tenant isolation. ### Invitations and Membership Owners, and any members granted the appropriate permissions, may invite additional members to an Organization. Invitees must have or create a Basic Memory account to join. Accepting an invitation to join an Organization does not cancel, replace, or otherwise affect any other Organization membership or subscription you already hold. If you own a separate Organization, that Organization and subscription continue unless you choose to change or cancel them. Owners may remove members from an Organization at any time. Content created by a removed member inside the Organization remains in that Organization. Removal from one Organization does not affect the removed member's Basic Memory account, their membership in other Organizations, or any separate subscription they own. ### Owner Responsibility The Owner is responsible for the Organization's use of Basic Memory Cloud, including: - Activity by members of the Organization - Content created, imported, shared, or published within the Organization - Agents, integrations, scripts, and automated tools operating in the Organization - Public links and sharing settings - Seat assignment and billing administration Owners are responsible for ensuring that members comply with these terms. ## Subscription and Billing Basic Memory Cloud is offered on a subscription basis. Pricing and plan details are displayed at checkout and on our pricing page. Some plans may include usage-based charges, prepaid credits, metered events, or custom pricing for agent infrastructure, automation, API usage, custom deployment, enterprise, or on-prem use. The checkout flow, billing portal, pricing page, or separate written agreement will describe the applicable usage unit, included credits, overage pricing, caps, billing timing, and any credit expiration rules. Partner, reseller, MSP, implementation partner, consulting partner, and managed-customer billing arrangements may use separate Commercial Terms, partner checkout flows, partner invoices, usage reports, committed seats, overage settings, overage pricing, credits, or written agreements. Those arrangements are governed by the [Partner Terms](https://basicmemory.com/partner-terms), applicable Commercial Terms, and any separate written agreement. ### Seats Each seat is for one individual human user and one account. The Owner's account is the first seat. Each additional human member requires an additional seat. Seat sharing is prohibited. You may not share one account or set of credentials among multiple people to avoid buying seats. Service accounts, bots, agents, and integrations do not require separate seats when they operate on behalf of a licensed human user and are not used to provide access to another person. High-volume automated or agent-fleet usage may require a separate plan or written agreement under the Acceptable Use Policy. ### Buying and Assigning Seats The Owner buys licenses for seats through our payment processor. Seats are assigned in the Basic Memory app. An available seat must exist before a new member can be assigned to that seat. Charges for added seats may be prorated for the remainder of the current billing period. The checkout, billing portal, or in-app billing flow will show the applicable price and timing. ### Individual to Team Upgrades Upgrading your own Organization from an individual subscription to a team subscription may cancel the old subscription and start a new one. Any prorated credit, charge, or billing adjustment will be shown in the billing flow or handled by the payment processor. Accepting an invitation to someone else's Organization is not an upgrade of your own subscription and does not affect any subscription you already own. ### Payment Processing Payments are processed by Polar.sh or another payment processor on behalf of Basic Memory LLC. By subscribing, you authorize recurring charges to your selected payment method until you cancel. If payment fails, we may suspend access to the Cloud Service until payment is resolved. For usage-based or credit-based plans, you authorize us and our payment processor to track usage events, apply available credits, and invoice or charge for metered usage according to the plan terms shown at checkout or agreed in writing. ### Cancellation and Refunds You may cancel your subscription at any time. Cancellation takes effect at the end of the then-current billing cycle unless the billing flow says otherwise. We do not provide partial-month refunds unless required by law or expressly stated at checkout. ## Data and Privacy ### Your Content You retain all rights to content you create, upload, import, or store in Basic Memory Cloud ("Your Content"). By using the service, you grant Basic Memory LLC a limited license to store, process, transmit, display, sync, index, and back up Your Content only as needed to provide, secure, maintain, and improve the service. ### Tenant Isolation Each Organization is provisioned as its own tenant. Organization content is stored and accessed independently from other Organizations. We do not share Organization content outside that tenant except as directed by authorized members, required by law, needed to provide the service, or described in our Privacy Policy. ### Access Within an Organization Content created within an Organization is accessible to members of that Organization according to their roles, project access settings, public sharing settings, and integrations. The Owner is responsible for configuring access and sharing settings appropriately. ### Export and Deletion You may export content from an Organization if your role allows it. You may delete content if your role allows it. Upon cancellation of an Organization's subscription, content in that Organization may be retained for 30 days so the Owner can resume the subscription or export data. Content may persist in encrypted backups for up to 90 days after that retention period, after which it is permanently deleted according to our normal backup lifecycle. ### Removed Members If you are removed from an Organization, content you created within that Organization remains with the Organization. Your Basic Memory account, other Organization memberships, and separate subscriptions are unaffected. ## Public Sharing Members with appropriate permissions may create public, read-only links to notes or other content within an Organization. Public links are treated as Organization-authorized access to the linked content. The Owner is responsible for public sharing settings and for content made public by Organization members. We may disable public links that violate these terms, the Acceptable Use Policy, applicable law, or the rights of others. ## Usage Limits and Acceptable Use Use of Basic Memory Cloud is subject to our [Acceptable Use Policy](https://basicmemory.com/acceptable-use). The Acceptable Use Policy explains prohibited uses, fair-use expectations, default resource limits, and how we handle automated or agent-driven activity. We may apply technical limits, throttling, suspension, or other restrictions to protect the service, prevent abuse, avoid noisy-neighbor impact, or enforce the Acceptable Use Policy. Human use of Basic Memory Cloud, ordinary collaboration, and reasonable ad hoc agent use are welcome. Using Basic Memory Cloud as product infrastructure, a high-volume hosted memory layer, or a large autonomous agent-fleet backend may require a separate credit-based, usage-based, custom, enterprise, or on-prem plan. ## Your Responsibilities When using Basic Memory services, you agree to: - Use the service responsibly and legally. - Not store, process, publish, or share illegal content. - Not attempt to access data you are not authorized to access. - Not interfere with service operation. - Not abuse, overload, scan, attack, or disrupt the service. - Keep your software, credentials, API keys, agents, and integrations secure. - Ensure that members of Organizations you own comply with these terms. - Take responsibility for agents, scripts, integrations, and automated tools operating under your account or within Organizations you own. - Comply with applicable laws and regulations. - Respect others in community spaces. ## Intellectual Property ### Open-Source Software Basic Memory core software is open source. Modifications and distributions must comply with the applicable licenses in the relevant repository. ### Your Content You retain all rights to Your Content. We do not claim ownership of it. ### Our Property This website, documentation, marketing materials, trademarks, logos, product names, and Basic Memory Cloud service are owned by Basic Memory LLC or its licensors. You may not use our branding in a way that suggests endorsement without permission. ## Third-Party Services Basic Memory integrates with third-party services such as AI assistants, payment processors, hosting providers, identity providers, and developer tools. - Your use of third-party services may be subject to their terms. - We are not responsible for third-party service availability or actions. - Integration availability may change. ## Disclaimers and Limitations ### "AS-IS" Service BASIC MEMORY SERVICES ARE PROVIDED "AS IS" AND "AS AVAILABLE" WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, UNINTERRUPTED OPERATION, ERROR-FREE OPERATION, ACCURACY, OR RELIABILITY. ### Limitation of Liability TO THE MAXIMUM EXTENT PERMITTED BY LAW, BASIC MEMORY LLC AND ITS AFFILIATES SHALL NOT BE LIABLE FOR INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, INCLUDING LOSS OF DATA, PROFITS, REVENUE, BUSINESS OPPORTUNITIES, GOODWILL, OR SERVICE AVAILABILITY. OUR TOTAL LIABILITY FOR ANY CLAIM SHALL NOT EXCEED THE AMOUNT YOU PAID US IN THE 12 MONTHS BEFORE THE CLAIM, OR $100, WHICHEVER IS GREATER. ### Backups We maintain backups for service operation, but you are responsible for maintaining your own backups and exports of critical data. ### Beta Disclaimer Beta services may be unstable, incomplete, or unavailable. Data loss is possible. No service level agreement applies during beta unless we separately agree in writing. ## Indemnification You agree to indemnify and hold harmless Basic Memory LLC, its officers, directors, employees, contractors, and agents from claims, damages, losses, liabilities, and expenses, including legal fees, arising from: - Your use of the service - Your Content - Your violation of these terms or the Acceptable Use Policy - Your violation of law or third-party rights - Activity by members of an Organization you own - Activity by agents, scripts, integrations, or automated tools operating under your account or within an Organization you own - Public links or shared content created from an Organization you own ## Changes to Terms We may update these terms from time to time. Changes will be posted on this page and reflected in the "Last updated" date. Changes are effective when posted unless we specify a later effective date. Your continued use of the services after changes become effective means you accept the updated terms. For material changes, we may provide additional notice by email, in-product notice, or another reasonable method. ## Dispute Resolution ### Informal Resolution Before filing a claim, contact us at so we can try to resolve the issue informally. ### Governing Law These terms are governed by the laws of the State of Texas, without regard to conflict of law principles. ### Jurisdiction Any disputes shall be resolved exclusively in the state or federal courts located in Austin, Texas. You consent to personal jurisdiction in those courts. ### Class Action Waiver Disputes must be resolved individually. You waive any right to participate in class actions or class-wide arbitration. ## General Terms ### Entire Agreement These terms, together with our Privacy Policy, Acceptable Use Policy, and, where applicable, our Partner Terms and Partner Program Policy, are the entire agreement between you and Basic Memory LLC for the services. ### Severability If any provision is found unenforceable, the remaining provisions continue in effect. ### No Waiver Failure to enforce any right or provision does not constitute a waiver. ### Assignment You may not assign these terms without our consent. We may assign them with notice. ### Force Majeure We are not liable for delays or failures due to circumstances beyond our reasonable control. ## Contact Questions about these terms? Contact us at: **Support:** **Legal:** **GitHub:** {rel=""nofollow""} **Address:** Basic Memory LLC, Austin, Texas