Open-Source Guide
What Is TM Second Brain? A Complete Guide to Persistent Memory for Humans and AI Agents
Taghi Molavi, Senior SEO Strategist and GEO Systems Architect at InTen, examines this topic.
Direct answer
Explore TM Second Brain (tm-second-brain): a $0.00 offline-first, Markdown-canonical persistent memory layer with BM25 search, secret redaction, Obsidian templates, and MCP support.
Classification: Project Documentation & Comprehensive Guide · Runtime Cost: $0.00 (Offline-First) · License: MIT
If you work with ChatGPT, Claude, or AI coding tools every day, you already know the most frustrating bottleneck in modern AI: digital amnesia. Yesterday you spent an hour explaining your brand voice, your Telegram customer objections, or your database concurrency rules. Today you open a fresh session, and the assistant acts as if it has never met you.
TM Second Brain (`tm-second-brain`) is built to eliminate that reset loop permanently. Created by Taghi Molavi, it is an open-source, multilingual, agent-agnostic Second Brain and Persistent Memory system. It gives both everyday users and multi-agent engineering teams a single, local-first, Markdown-canonical memory layer that runs completely offline at $0.00 cost across macOS, Linux, and Windows.
Executive Summary (TL;DR)
* The Core Problem: AI tools forget context between sessions, bleed instructions across unrelated projects, and silently overwrite changing facts without leaving an audit trail. * The Solution: Store all durable knowledge in plain Markdown files + YAML frontmatter on your own machine, powered by Python 3.10+ standard library only (zero mandatory external dependencies, zero API keys, $0.00 default cost). * Who It Is For: Non-technical founders, content creators, and marketing teams who want an organized, private knowledge vault in Obsidian—as well as software engineers running Claude Code, OpenAI Codex, Gemini CLI, OpenCode, Goose, Antigravity, or Hermes across local and server nodes. * Official Repository: tmolavi/tm-second-brain on GitHub
Plain-English Glossary (Every Term Explained Simply)
Whether you are a business owner or a systems architect, here is what the core terms in the architecture mean in plain language:
| Term | Plain-English Meaning | Real-World Example |
|---|---|---|
| Second Brain | A trusted, organized external memory outside your head where notes, decisions, rules, and lessons live so nothing gets lost. | Think of a smart notebook that not only stores everything you learn, but finds the exact rule you need in milliseconds. |
| Markdown Vault | A normal folder on your computer where every note is saved as a simple .md text file. Your knowledge is never locked inside a paid cloud app. | Even 20 years from now, any basic text editor can open and read your entire knowledge base. |
| YAML Frontmatter | A short ID card at the top of each note (project name, status, confidence level, privacy flag) so both humans and AI agents know where a fact belongs. | Like a label on an office folder: "Project X · Verified on Date Y · Private". |
| BM25 Search | A proven, zero-cost ranking algorithm that finds the most relevant notes by keyword importance without needing expensive AI embedding servers. | Like an expert librarian who knows which words in a document carry the real meaning. |
| SQLite FTS5 | A lightweight local search index built alongside your Markdown files so queries finish instantly. If deleted, it rebuilds cleanly from your files. | Like the alphabetical index at the back of a book—the book itself is the source of truth. |
| Wikilinks (`[[Links]]`) | Connecting one note to related notes inside the text so ideas and decisions form a navigable knowledge graph. | Linking a "Pricing Policy" note to "Telegram Campaign Rules" lets the system surface both together. |
| Provenance | Recording who wrote a memory (human or specific AI agent), where it came from, and whether it has been verified. | You never have to wonder "who changed this number?"—the origin is always attached. |
| MCP (Model Context Protocol) | A universal standard interface that lets different AI tools connect safely to your local memory and tools. | Think of it as USB-C for AI agents—one standard port instead of custom glue for every app. |
| Secret Redaction | Automatic detection and masking of API keys, tokens, and passwords before any data leaves a boundary or enters an export. | If you accidentally paste a payment key into a note, it will not leak to an external tool. |
Why Typical AI Memory Setups Break Down
Most teams today use several tools in parallel: an IDE assistant on a laptop, a CLI agent in the terminal, and automated bots handling customer channels. Without a unified memory layer, four failures show up quickly:
- Siloed Context: What you taught Claude Code yesterday is invisible to Codex or your desktop assistant today.
- Cross-Project Contamination: Tone-of-voice rules for a B2B landing page leak into personal notes or an unrelated codebase.
- Silent Overwrites: When a policy, price, or technical decision changes, naive memory stores overwrite the old fact—erasing *why* the previous decision existed.
- Subscription Lock-In: Cloud memory services charge recurring fees and store sensitive company knowledge on third-party servers.
tm-second-brain solves all four by keeping Markdown on your disk as the canonical truth and enforcing strict project and environment isolation.
Real-World Examples Across Channels & Teams
1. Sales, Marketing & Customer Channels (Website, Telegram, Instagram, CRM)
Imagine running a multi-channel brand where an AI assistant drafts landing pages, answers Telegram inquiries, and updates CRM notes: * The Challenge: Your website needs formal technical specs, Telegram needs fast conversational answers with current promo rules, and Instagram needs a human brand voice—all without mixing up old prices. * With TM Second Brain: Each project gets strict isolation (scope: project). Brand guidelines, customer FAQs, and objection-handling playbooks live in one verified vault. When pricing or warranty terms change, the correct command marks the old note superseded and links the new active record with a reason in .tm-brain/corrections.jsonl. Every channel stays consistent. * Pairing this memory layer with Digital Twin & Autonomous Workflows turns scattered customer interactions into a reliable conversion engine.
2. Personal Knowledge Management & Content Creation (Everyday Users)
* The Challenge: Book highlights, article ideas, and daily reflections pile up across folders until you can never find them again. * With TM Second Brain: Running init --template personal-knowledge sets up a complete Obsidian-ready PARA structure (00_Inbox through 04_Archive) plus Daily Notes/. Anything marked private: true or placed in 02_Areas/Personal/ is strictly excluded from AI agent reads and exports.
3. Business Operations & Leadership Teams
* The Challenge: Teams forget why a vendor was replaced or what was agreed in last month's strategy call. * With TM Second Brain: The business-project template organizes a 3-Year to Weekly Goal Cascade alongside Projects/, Meetings/, Decisions/, and an Obsidian Home.base table view. Searching a topic or running expand traces connected meetings and decisions in milliseconds.
4. Multi-Agent Software Engineering & Distributed Nodes
* The Challenge: As illustrated in the architecture diagram above, a modern engineering workflow may span Mac Hermes (local desktop), Antigravity (engineering IDE), Finland Hermes (remote server), and Main Hermes & Hamzad Core. * With TM Second Brain: The developer-agent template creates brain/ (North Star, Key Decisions, Patterns, Gotchas), Skills/, and Knowledge Graph.canvas. Coding agents—OpenAI Codex, Claude Code, Gemini CLI, OpenCode, Goose, and Antigravity—connect via tm-brain mcp or install-adapter, while environment boundaries keep personal Mac memory strictly separated from production servers.
Technical Architecture & Engineering Guarantees
For engineers evaluating tm-second-brain for production use, the system is built on three clean layers:
Layer 1: Canonical Vault Storage
* Every durable memory is stored as Markdown with YAML frontmatter (mem_<YYYYMMDD>_<hash>). * Explicit lifecycle states: draft → active → superseded → archived. * Immutable audit trails in agent-log/YYYY-MM.md and .tm-brain/corrections.jsonl. * The SQLite FTS5 cache (.tm-brain/index.db) is 100% rebuildable from disk.
Layer 2: Pure-Python Core (tm_second_brain)
Written exclusively with the Python 3.10+ standard library (dependencies = []), ensuring identical behavior on macOS, Linux, and Windows: * Tiered Hybrid Retrieval (`RetrievalBackend`): * Tier 0 (Default — $0.00): Deterministic Python BM25 + SQLite FTS5 + wikilink graph expansion (expand) + recency/confidence weighting. * Tier 1 (Optional Local — $0.00): Pluggable adapters for @tobilu/qmd or local Ollama (nomic-embed-text, llama3.2, qwen2.5). * Tier 2 & Tier 3 (Optional Cloud): Opt-in support for Gemini Free Tier, Groq, or paid providers—never triggered silently, and never sent private: true records. * Conflict Detection & Correction History: Checks active memories in the same scope before writing; corrections append supersedes / superseded_by links instead of overwriting. * SHA-256 Verified Backups: Creates .tar.gz archives with checksum verification and automatic pre-restore safety snapshots. * Human-in-the-Loop Learning: Repeated corrections generate L1 Draft proposals; updating SKILL.md or AGENTS.md requires explicit L2 User Approval.
Layer 3: Adapters & Interop
* Obsidian: Safe .md read/write with auto-backup before overwrite, preserving .base and .canvas files. * First-Class TM Bridges: HamzadBridge (non-duplicating integration with MemoryService), MainHermesAdapter, and HermesPersonalDesktopAdapter. * Agent Harnesses: One-command adapter installation (codex, claude-code, gemini-cli, opencode, goose, antigravity) plus stdio MCP Server (tm-brain mcp).
Quick Start in Under 60 Seconds
# 1. Initialize a vault with a starter template (never overwrites existing files)
python3 -m tm_second_brain.cli --vault ./my-vault init --template developer-agent
# 2. Store and search memories completely offline ($0.00)
python3 -m tm_second_brain.cli --vault ./my-vault remember \
--title "Use WAL mode" --body "Enable SQLite WAL for concurrent readers." --project core
python3 -m tm_second_brain.cli --vault ./my-vault search "WAL" --project core
# 3. Install an agent adapter (codex | claude-code | gemini-cli | opencode | goose | antigravity)
python3 -m tm_second_brain.cli --vault ./my-vault install-adapter codex
# 4. Create a SHA-256 verified backup
python3 -m tm_second_brain.cli --vault ./my-vault backup ./vault-backup.tar.gzFrequently Asked Questions
Do I need to be a developer to use TM Second Brain?
No. Business owners, writers, and teams can open the vault directly in Obsidian using the personal-knowledge or business-project templates like a structured smart notebook. The CLI and MCP server are there for teams connecting AI coding or workflow agents.
How much does it cost to run?
$0.00 by default. Core memory storage, BM25 + wikilink graph search, conflict tracking, privacy redaction, and SHA-256 backups run 100% locally in Python without any API keys or cloud subscriptions.
How is TM Second Brain different from cloud memory tools?
Cloud memory platforms keep your data on external servers and tie retrieval to recurring API bills. tm-second-brain treats local Markdown files as the canonical source of truth, works offline, and preserves full correction provenance.
How does it protect private notes and API keys?
Notes tagged private: true or stored in configured private_paths are excluded from agent recall and exports. Built-in Secret Redaction also masks API keys and tokens across MCP, exports, and bridges.
How can I deploy a unified brand memory and GEO architecture for my company?
If you want to connect persistent brand memory with AI search visibility (GEO) and multi-channel lead conversion, you can request a project review or start by auditing your site with the free Molavi Web Intelligence Engine.
Related Reading & Next Steps
* Official GitHub Repository: tmolavi/tm-second-brain * Agent Skills & MCP: How to Organize AI Agent Skills (MCP Agent Skills Hub) * Project Discovery: Agent Project Discovery Before Editing * Architecture & Services: Digital Twin & Autonomous Workflows · GEO & AI Visibility Audit · Technical Proof & Open Source