DOCSEARCHbyAlgolia
Submit Docs

Obsidian Mind Documentation

repository·main·Indexed 25 days ago

https://github.com/breferrari/obsidian-mind

An Obsidian vault designed to provide AI coding agents—such as Claude Code, Codex, and Gemini CLI—with persistent, compounding memory. It features a structured system for tracking organizational competencies, a Model Context Protocol (MCP) server for cross-repo access, and an optional QMD semantic search integration. The system includes 18 specialized slash commands and various subagents to automate vault maintenance, performance review preparation, and knowledge lifecycle management.

Tokens
21.7K
Snippets
27
Records
115
Agent score
88%

What's inside Obsidian Mind

  1. System Overview of obsidian-mind

    main

    The obsidian-mind system is built as a layered architecture on top of a standard Obsidian vault. It consists of four primary layers:

    1. The Vault: A collection of Markdown files, frontmatter, and wikilinks that serve as the persistent state.
    2. Hook Pipeline: TypeScript scripts located in .claude/scripts/ that are triggered by an agent harness at specific lifecycle events (e.g., session start, after writes, before compaction).
    3. Semantic Search Layer (QMD): A CLI and SQLite index with an MCP server that provides semantic search capabilities, scoped via vault-manifest.json.
    4. om MCP Server: A 'vault-as-a-service' layer that allows agent sessions in different repositories to search, read, and record data back into the vault.

    All layers coordinate through a single source of truth: vault-manifest.json.

  2. Understand the vault directory structure

    main

    The vault is organized into functional areas:

    • bases/: Dynamic database views (e.g., Work Dashboard, Incidents, People Directory).
    • work/: Project management (active/, archive/), incidents/, and 1-1/ meeting notes.
    • org/: Organizational knowledge (people/, teams/).
    • perf/: Performance tracking (Brag Doc.md, competencies/, evidence/).
    • brain/: High-level context (North Star.md, Key Decisions.md, Patterns.md).
    • reference/: Technical knowledge and architecture maps.
    • thinking/: Scratchpad for drafts.
    • templates/: Obsidian templates with YAML frontmatter.
    • .claude/: AI configuration (commands, agents, skills, and settings).

  3. Understand the Search and Recall Architecture

    main

    The system uses a multi-layered approach to search and memory recall. It acts as an MCP client to the vault's qmd server.

    Key architectural decisions:

    • Filter the result, never the query: The index covers the entire vault. To ensure security and scoping, the system retrieves results from the index and then filters them against the caller's allowed paths/policies. This prevents callers from accidentally or intentionally bypassing scope via query construction.
    • Over-fetch, then trim: Because filtering happens on the result set, the client requests max(limit * 4, 20) items from qmd to ensure that after filtering, the requested limit can still be satisfied.
    • Conditional HyDE: Hypothetical Document Embeddings (HyDE) are only used for queries that are at least four words long and 'question-shaped' to optimize performance.
    • Explicit Degradation: If qmd fails, the system degrades to lexical fallback (per-token, title, and body) rather than reporting an empty vault. A failed qmd call does not disable search for the entire session.

  4. Navigate the Obsidian Mind Home Dashboard

    main

    The Home.md file serves as the central vault entry point, utilizing embedded dashboards and quick links to provide a high-level overview of your workspace. It aggregates data from various specialized files using Obsidian's transclusion syntax (![[File#Heading]]).

    Key sections available on the Home dashboard include:

    • Current Focus: Displays the current focus from the North Star note.
    • Active Work: Shows active projects and tasks via the Work Dashboard.base.
    • Recently Touched: Lists notes modified in the last 7 days from Recently Touched.base.
    • Incidents: Aggregates incident reports from Incidents.base.
    • Recent 1:1s: Displays meeting history from 1-1 History.base.
    • People: Shows the directory view from People Directory.base.

    Quick Links for rapid navigation:

    • [[Index|Work Notes]]
    • [[People & Context]]
    • [[Brag Doc]]
    • [[Memories]]
    • [[North Star]]
    • [[Skills]]

  5. Understand the obsidian-mind architecture and lifecycle hooks

    main

    The project uses a hybrid approach: procedural code (hooks in .claude/scripts/) manages the environment, while Agents handle content. This ensures tasks like classification, validation, and indexing are reproducible and testable.

    Lifecycle Hooks

    HookTriggerFunction
    🚀 SessionStartOn startup/resumeRe-indexes QMD, injects North Star goals, active work, recent changes, tasks, file list, and repository hygiene flags.
    💬 UserPromptSubmitEvery messageClassifies content (decisions, events, achievements, 1:1s, architecture, people, project updates) and injects routing prompts.
    ✍️ PostToolUseAfter writing .mdValidates frontmatter and wikilinks, intercepts misplaced memory files, and marks oversized notes for splitting.
    💾 PreCompactBefore context compressionBacks up session records to thinking/session-logs/.
    🏁 StopOn session endRuns checklists and hygiene scans (similar to SessionStart) to detect drift.
    TIP

    You can interact with the Agent naturally; the hooks handle the routing automatically.

  6. Understand the `om` MCP server surfaces

    main

    The om MCP server provides four distinct interaction surfaces that allow a coding session (like Claude) to interact with your Obsidian vault. Understanding these is critical for knowing how to trigger different types of memory access:

    SurfaceDirectionDescriptionTriggered By
    instructionsVault $\rightarrow$ SessionThe vault's rules/prohibitions injected into the session's system prompt.Automatic (on connect)
    toolsSession $\rightarrow$ VaultCapabilities like search, expand, recall, remember, record_work, reason, and health.The AI Model
    resourcesSession $\rightarrow$ VaultNotes accessible via vault://note/<path> URIs.The Model or Client
    promptsHuman $\rightarrow$ VaultSlash commands like recall_topic or prior_art.The Human User

    Note on Prohibitions: Rules in instructions (e.g., "never put a session URL in a commit") are enforced by the model, but positive instructions (e.g., "consult the vault before answering") are advisory. To ensure a model actually looks at your vault, use the prompts surface, as human-invoked prompts bypass model decision-making.

  7. Understand the repository structure and Bases

    main

    The repository is organized into functional directories, with bases/ providing dynamic database views of your notes. Home.md acts as the dashboard by embedding these views.

    Core Directories

    • work/: Contains active/ projects, archive/, incidents/, and 1-1/ meeting notes.
    • org/: Contains people/ and teams/ notes.
    • perf/: Contains the performance tracking data (Brag Doc.md, competencies/, evidence/).
    • brain/: Contains high-level context (North Star.md, Key Decisions.md, Patterns.md).
    • reference/: Codebase knowledge and architecture.
    • templates/: YAML frontmatter templates for various note types.
    • .claude/: Contains commands/, agents/, and skills/.

    Available Bases (Database Views)

    • Work Dashboard: Active projects filtered by quarter/status.
    • Recently Touched: All notes sorted by actual modification time.
    • Incidents: Events sorted by severity and date.
    • People Directory: Roles and teams from org/people/.
    • 1:1 History: 1:1 notes sorted by person and date.
    • Review Evidence: PR scans and evidence grouped by person/cycle.
    • Competency Map: Competencies with backlink evidence counts.

  8. Understand the Vault Structure

    main

    The vault is organized into several functional directories:

    • work/: Contains active/ projects, archive/ (organized by year), incidents/, and 1-1/ meeting notes (<name> YYYY-MM-DD.md).
    • org/: Organizational knowledge including people/ (one note per person), teams/, and People & Context.md.
    • perf/: Performance tracking including Brag Doc.md, brag/ (quarterly notes), competencies/, evidence/, and review cycle artifacts.
    • brain/: Core focus areas like North Star.md (goals), Key Decisions.md, Patterns.md, and Skills.md.
    • reference/: Codebase knowledge and architecture maps.
    • thinking/: Scratchpad for drafts (delete after promoting insights).
    • templates/: Obsidian templates with YAML frontmatter.
    • .claude/: Agent configuration including commands/, agents/, scripts/, and skills/.
    • .scripts/: Vault-level tools (e.g., QMD bootstrapping).
    • .shardmind/: (Optional) ShardMind sidecar for advanced features via shardmind CLI.

  9. Understand the Work Notes folder structure

    main

    Work notes are organized into the following directory structure:

    • active/: Contains current projects.
    • archive/: Contains completed work, organized by year.
    • incidents/: Contains incident documentation.
    • 1-1/: Contains meeting notes.

  10. Navigate the Memories index

    main

    The Memories index serves as a central repository for persistent context and knowledge retained across sessions. Use the following linked topics to access specific knowledge domains:

    • Key Decisions: Architectural and workflow decisions.
    • Patterns: Recurring patterns and conventions discovered across work.
    • Gotchas: Known issues, pitfalls, and previous errors.
    • People & Context: Organizational structure, team information, review history, and interpersonal dynamics.
    • North Star: The living goals document (recommended to read at the start of a session).
    • Skills: Documentation for custom slash commands and workflows.

  11. System Requirements for obsidian-mind

    main

    To use obsidian-mind, ensure your environment meets the following requirements:

    • Obsidian: version 1.12 or higher (required for CLI support).
    • Claude Code: Installed and configured.
    • Node.js: version 22+ LTS (required for hook scripts. Note: Hook scripts use the --experimental-strip-types flag to run TypeScript directly. If Node flags change in future releases, you must update the hook commands in .claude/settings.json, .codex/hooks.json, or .gemini/settings.json).
    • Git: Installed (used for version history).
    • QMD (Optional): Recommended for semantic search capabilities.

  12. Manage Vault Upgrades

    main

    Template versions are tracked in vault-manifest.json. The /om-vault-upgrade command detects older versions using file fingerprints.

    Stability Guarantees: To prevent breaking consumers, the following elements are guaranteed to remain stable:

    • Manifest keys: qmd_index, infrastructure, user_content_roots, frontmatter_required, memory_root.
    • Hook script names: Under .claude/scripts/.
    • Launcher path: The om-mcp.mjs path used in .mcp.json.
    • Folder layout: The structure for user content.

    Note that memories/ is listed in user_content_roots to ensure it is preserved during upgrades.