Basic Memory: The Decision and Alignment Vault
Basic Memory is a long-term memory system shared between you and your AI assistants. It ensures that strategic decisions, project boundaries, and agreed-upon rules survive when starting a new chat session or switching between different AI tools.
The Sticky Note on the Monitor: Why Basic Memory Exists
Imagine hiring an extremely brilliant assistant who unfortunately suffers from short-term memory loss every time they leave the room:
- If they only rely on recent chat messages, they quickly lose the big picture. After an hour of working, they forget what you originally agreed on. They might spend three days redesigning your entire database or building a massive web application from scratch, completely forgetting your initial instruction: "We do not need a website; we only need a 50-line data script."
- Basic Memory is the yellow sticky note glued to the computer monitor. It contains the house rules signed by the owner:
- Rule 1: We do NOT touch live financial or production accounts.
- Rule 2: We do NOT build complex web interfaces; keep it as a simple command-line script.
- Rule 3: Stop as soon as this specific feature works.
Every time the assistant starts a significant task, it is required to look at this sticky note first. Because the rules are written down outside the chat window, the assistant never goes rogue or builds unwanted software platforms.
How It Protects Projects
| Core Principle | Mechanism | Why It Matters |
|---|---|---|
| Single Source of Truth | Maintains one concise summary of accepted goals and red lines per project | Prevents conflicting instructions from confusing the agent |
| Lazy Retrieval | Never loads full memory on startup; retrieves only the active project note | Zero context clutter, keeping the agent's attention sharp |
| Human Veto Power | Routine coding tools can never edit rules without explicit owner approval | Completely protects projects from AI hallucination and runaway drift |
The Real-World Lesson: Stopping the "Runaway Project"
When AI coding agents lose track of their original instructions, they exhibit compensatory over-engineering: feeling uncertain, they defensively invent new layers, extra configuration files, and bloated frameworks. Basic Memory freezes the project's boundaries, keeping work small, direct, and under human control.
How It Works with Other Tools
A complete AI workflow uses both high-level rules and low-level search tools working together:
- Basic Memory tells the AI What and Why:
"We are improving backtest performance, but we must never touch real customer balances." - zvec-grep tells the AI Where:
"The calculation logic lives in file X, lines 140 to 180." - The AI executes the work:
It reads only those 40 lines, applies the fix, verifies it, and stops.
Related Notes & Connected Systems
- The Bigger Picture: Agent Memory and Hierarchical Retrieval — The complete 4-tier model showing how human intent, concepts, and code stay aligned.
- The Concept Garden: QMD — The local search library for domain theories and past design lessons.
- The Code Locator: zvec-grep (zg) — The precision search radar that helps the AI find code without reading whole files.
- The Connector Standard: Model Context Protocol (MCP) — The universal plug that lets AI assistants communicate with Basic Memory.
Official Resources & References
- GitHub Repository: basicmachines-co/basic-memory
- PyPI Package: basic-memory