Skip to main content
Glama

๐Ÿง  Brain

English Documentation ยท ไธญๆ–‡ๆ–‡ๆกฃ ยท Architecture

CLI-first Obsidian for LLMs: Build your second brain with Markdown notes, bi-directional wikilinks, and high-performance full-text search. Implemented with zero external dependencies using the Python standard library.


๐Ÿ›๏ธ Vault Architecture: Core, Brain & Daily

The vault directory (defaults to ~/.brain or $BRAIN_VAULT) organizes memory into distinct tiers:

~/.brain/
โ”œโ”€โ”€ core/                # Core directives, identity & soul [inti brain][soul]
โ”‚   โ”œโ”€โ”€ soul.md          # Agent identity, persona & foundational guidelines
โ”‚   โ””โ”€โ”€ memory.md        # Persistent facts & long-term user profile
โ”œโ”€โ”€ brain/               # Knowledge notes [judul][isi]
โ”‚   โ”œโ”€โ”€ Concept A.md     # [Title].md holding title and Markdown content
โ”‚   โ””โ”€โ”€ Concept B.md     # Interconnected with [[wikilinks]] and #tags
โ”œโ”€โ”€ daily/               # Episodic logs & journal entries
โ”‚   โ””โ”€โ”€ 2026-11-10.md    # Daily notes auto-created by date
โ””โ”€โ”€ README.md            # Vault overview and quick reference
  • core/ [Core Brain / Soul]: Fundamental directives, persona, and core rules. Managed via brain core and MCP tools brain_get_core / brain_save_core.

  • brain/ [Title / Content]: Specific domain knowledge, ideas, documentation, and conceptual notes. Managed via brain new, brain search, etc.

  • daily/ [Episodic Journal]: Daily logs and task lists managed via brain daily.


Related MCP server: akatsuki

โœจ Features

  • ๐Ÿ“ Markdown Notes: Clean files with simple frontmatter (tags / aliases) and standard Markdown formatting.

  • ๐Ÿ”— Obsidian-Style Wikilinks: Supports [[Note]], [[Note|alias]], and [[Note#section]] with bi-directional backlink tracking.

  • ๐Ÿท๏ธ Tagging System: #ai, #notes/ml, with support for nested and international tags.

  • ๐Ÿ” Full-Text Search Engine: Fast word-token search with built-in unigram + bigram support for CJK languages (no external tokenizer required). Weighted by title (3x), tags (2x), and content.

  • ๐Ÿ•ธ๏ธ Interactive & Exportable Graph: ASCII adjacency view, Graphviz DOT, and JSON exports.

  • ๐Ÿ“… Daily Notes: Automatic template creation for daily planning and episodic logs.

  • ๐ŸงŠ Integrity Tools: Orphan note detection, vault statistics, and rename with automatic global wikilink rewriting.

  • ๐Ÿ’ป Interactive REPL: Run brain repl for an interactive shell session.

  • ๐Ÿค– MCP Server (Model Context Protocol): Seamless long-term memory for Claude Code, Cursor, Codex, and any MCP-compatible AI client.


๐Ÿš€ Installation

Install or update Brain with a single command via curl | bash:

curl -fsSL https://raw.githubusercontent.com/Iky969/brain-llm/main/install.sh | bash

Manual Install via Git

git clone https://github.com/Iky969/brain-llm.git
cd brain-llm
pip install -e .

โšก Quick Start

# 1. Initialize the vault (~/.brain)
brain init

# 2. View or edit core identity [inti brain][soul]
brain core
brain core -e

# 3. Create domain knowledge notes in brain/ [judul][isi]
brain new "Machine Learning" -t ai ml
brain new "Deep Learning" -t ai ml -c "# Deep Learning\n\nBranch of [[Machine Learning]]."

# 4. Search and browse
brain search "learning"     # Full-text search
brain list                  # List notes with folder/category indicator
brain links "Deep Learning" # Inspect forward links and backlinks
brain tags                  # View all tags
brain graph                 # Render ASCII graph (-f dot / -f json also available)
brain stats                 # View vault statistics
brain daily                 # Open or view today's daily log
brain repl                  # Enter interactive shell

Global Options

  • --vault <dir>: Custom vault directory (defaults to ~/.brain, or environment variable BRAIN_VAULT).

  • EDITOR: Editor used by brain open and -e flags (e.g. export EDITOR=nano).


๐Ÿ“– CLI Command Reference

Command

Aliases

Description

init

initialize, ๅˆๅง‹ๅŒ–

Initialize or verify vault structure (core/, brain/, daily/)

core [name]

soul, inti

View, edit (-e), set (-s), or list (-l) core soul memory

new <title>

create, add, ๆ–ฐๅปบ

Create note in brain/ (-c content, -t tags, -e edit, --folder)

open <title>

edit, ๆ‰“ๅผ€

Open note in $EDITOR

show <title>

view, cat, read, ๆŸฅ็œ‹

Display note content (--raw for unhighlighted output)

list

ls, ๅˆ—่กจ

List notes with folder and tag columns (-n limit, --folder)

search <query>

find, grep, ๆœ็ดข

Full-text search across all notes (-n limit)

delete <title>

rm, remove, ๅˆ ้™ค

Delete note (-f to skip confirmation)

rename <old> <new>

mv, ้‡ๅ‘ฝๅ

Rename note and rewrite all [[wikilinks]] in the vault

links <title>

backlinks, ้“พๆŽฅ

Inspect outlinks and incoming backlinks

tags [tag]

tag, ๆ ‡็ญพ

List all tags or filter notes by a tag

daily

today, journal, ๆ—ฅ่ฎฐ

View or create today's daily log (-e to edit)

graph

ๅ›พ่ฐฑ

Export link graph (-f ascii|dot|json, -o <file>)

orphans

ๅญค็ซ‹

List orphan notes (notes with no inlinks or outlinks)

stats

status, info, ็ปŸ่ฎก

Vault statistics (notes, links, tags, orphans)

repl

shell, interactive, ไบคไบ’

Enter interactive REPL shell

mcp

serve

Launch MCP stdio server for LLM integration


๐Ÿค– LLM & MCP Integration

Brain provides a built-in MCP (Model Context Protocol) server exposing tools for LLM agents:

  • brain_get_core: Retrieve core directives and soul identity.

  • brain_save_core: Update core persona and persistent directives.

  • brain_search: Full-text search across all notes with relevance scoring and snippets.

  • brain_get: Fetch the full Markdown content of a note.

  • brain_save: Create or update a note in the knowledge base.

  • brain_delete: Delete a note.

  • brain_list: List notes with category and tag filtering.

  • brain_daily: Retrieve or append to today's daily log.

  • brain_links: Inspect forward links and backlinks.

  • brain_graph: Export link graph for contextual graph navigation.

  • brain_tags: View tags index.

  • brain_stats: Overview of vault health and stats.

Claude Code Setup

claude mcp add brain -- brain --vault ~/.brain mcp

Cursor Setup (~/.cursor/mcp.json)

{
  "mcpServers": {
    "brain": {
      "command": "brain",
      "args": ["--vault", "/home/your_user/.brain", "mcp"]
    }
  }
}

๐Ÿ“„ License

This project is licensed under the MIT License ยฉ 2026 Iky969.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Local MCP server for querying and maintaining a Markdown vault. Provides full-text search, backlinks, note retrieval, and optional confined write tools, without sending the whole vault to the client context.
      22
      110 PyPI
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes a living systems memory vault to autonomous agents, letting them search notes with BM25 ranking, read sections within token budgets, extract API/port/schema contracts, compute dependency blast radius, and run machine-verifiable invariant assertions before mutating code. It also supports surgical frontmatter edits, schema linting, wikilink integrity checks, and worklog recording, over stdio MCP.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes a local Markdown vault to AI agents over stdio, letting them search, read, create, update (with mtime-guarded writes), and append notes, as well as list and manage saved views. Write permissions can be toggled per group in settings, and all changes land as plain Markdown/YAML files in the chosen folder.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Serves a Markdown memory vault to AI agents over MCP, letting them write, search, edit, and verify memories while full-text and graph indexes stay in sync in the background. Combines SQLite FTS5 retrieval with a Graphiti temporal knowledge graph so agents can recall both documents and entity facts over time.
      8
      MIT