obsidian mind - Moses Yebei

The Problem

AI coding agents start every session with zero context—no memory of goals, team dynamics, past decisions, or completed work. Users re-explain the same context repeatedly, and knowledge never compounds across sessions. This repo solves that by turning an Obsidian vault into persistent agent memory.

What This Does

obsidian-mind is a self-organizing Obsidian vault with hooks for Claude Code, Codex CLI, and Gemini CLI. It captures session context, meeting notes, incidents, and performance reviews into structured Markdown files under work/, org/, and perf/. Commands like /om-standup and /om-dump trigger the agent to read and update the vault automatically.

The core logic lives in .claude/scripts/—67 TypeScript files handling session start, memory indexing, note hygiene, and QMD semantic search integration. The .claude/agents/ directory defines specialized personas (e.g., slack-archaeologist.md, brag-spotter.md) that handle specific capture workflows. The bases/ folder contains Obsidian Bases for structured data like people directories and work dashboards.

How It Is Wired

Execution starts at main in .claude/scripts/generate-memory-index.ts:51, which reaches 72 functions. The session flow begins with .claude/scripts/session-start.ts, which reads hook input from stdin, checks the vault state, and formats context for the agent. The hook-io module (11 importers) handles stdin/stdout I/O and is the most-connected module—changing it breaks the most code.

Key routing happens through active-hygiene.ts (18 functions, 6 types), which parses open-loop configs and manages note cleanup, and qmd-refresh.ts, which triggers semantic search index rebuilds. The main-guard and regex modules are pure utilities with zero instability—safe to modify.

The call graph shows isMarkdownFilename called from 9 places and escapeRegex from 6—these are the highest-blast-radius functions. One function reads/writes a database (QMD index). The module graph has no circular dependencies (0 modules in cycles), which keeps refactoring tractable.

How To Use It

Setup (from README):

npm install -g shardmind
mkdir my-vault && cd my-vault
shardmind install github:bre
# or: git clone https://github.com/moses-y/obsidian-mind

Configuration: No env vars required. The vault uses .claude/settings.json for Claude Code settings and .codex/hooks.json/.gemini/settings.json for other CLIs. QMD integration needs the qmd binary installed separately.

Running it: Invoke commands in your agent CLI: /om-standup, /om-dump <text>, /om-incident-capture <url>, /om-wrap-up. Tests run via npm test in .claude/scripts/.

Real-World Use

A developer starts a session: "start session." The agent reads brain/North Star.md, checks work/active/, scans recent memories, and reports: "You're blocked on the BE contract. Your 1:1 with Sarah is tomorrow—review brief is ready." After the meeting, /om-dump creates work/1-1/Sarah 2026-03-26.md, updates org/people/Sarah Chen.md, adds a Decision Record, and appends to perf/Brag Doc.md.

Code Health & Issues

Measured analysis (static, not opinion) found 13 medium-severity findings across 4 kinds:

Med - High branching density (x7): session-start.ts has 86 branch points over 247 lines; qmd.ts and active-hygiene.ts similar. Decompose decision-heavy logic.
Med - Deep nesting (x4): Max indentation depth 6 in active-hygiene.ts, session-start.ts. Flatten with guard clauses.
Med - Duplicated code blocks: 11 repeated 6-line blocks across 10 files. Extract shared helpers.
Med - Oversized file: tests/session-start.test.ts at 651 lines. Split by responsibility.

SDLC observations:

High - No lockfile: .claude/scripts/package.json has no lockfile—non-reproducible builds.
High - Push to main: .github/workflows/release.yml pushes to main directly, bypassing PR review.
Med - No least-privilege token: 3 workflows declare no permissions block.
Med - No dependency scanning: No dependabot.yml or dependency-review-action in CI.
Med - Token persists after checkout: persist-credentials: false not set in release workflow.
Low - No job timeouts: 4 workflows lack timeout-minutes.

Tests exist (36 files) and CI runs on GitHub Actions. No committed secrets found.

The Bottom Line

This is a well-architected system for persistent agent memory with clean module boundaries and no circular dependencies. The TypeScript core is solid, but the missing lockfile and CI hardening (token permissions, dependency scanning) are production blockers. Worth adopting if you use Claude Code heavily and want structured memory—just fix the CI issues first.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

187 files

Markdown73
TypeScript67
JSON14
YAML7

ReactExpress

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0[".claude<br/>62 modules"] g1[".shardmind<br/>3 modules"] g2[".github<br/>2 modules"] g2 -->|3| g0 g0 -->|2| g1 g0 -->|2| g2

Module dependencies

The 10 most depended-upon modules of 68, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0__claude_scripts_lib_hook_io["hook-io"] n1_de_scripts_lib_session_start["session-start"] n2_laude_scripts_lib_main_guard["main-guard"] n3__claude_scripts_lib_regex["regex"] n4_laude_scripts_tests__helpers["_helpers"] n5__claude_scripts_lib_qmd["qmd"] n6_aude_scripts_lib_qmd_refresh["qmd-refresh"] n7_e_scripts_lib_active_hygiene["active-hygiene"] n8__claude_scripts_lib_matcher["matcher"] n9_ude_scripts_lib_memory_index["memory-index"] n7_e_scripts_lib_active_hygiene --> n3__claude_scripts_lib_regex n7_e_scripts_lib_active_hygiene --> n1_de_scripts_lib_session_start n8__claude_scripts_lib_matcher --> n3__claude_scripts_lib_regex n6_aude_scripts_lib_qmd_refresh --> n5__claude_scripts_lib_qmd n6_aude_scripts_lib_qmd_refresh --> n0__claude_scripts_lib_hook_io n6_aude_scripts_lib_qmd_refresh --> n1_de_scripts_lib_session_start n1_de_scripts_lib_session_start --> n3__claude_scripts_lib_regex

Findings

LowDependencies declared without a lockfile - non-reproducible builds .claude/scripts/package.json

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium4

low1

Commit a lockfile beside the manifesthigh

.claude/scripts/package.json

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Open a pull request instead of pushing to the default branchhigh

.github/workflows/release.yml

git push origin main

Automated commits land on the branch that deploys, with no test having run against the result.

Fix: Push to a bot branch and open a pull request, or restrict the push to a tag ref.

Declare least-privilege permissions for GITHUB_TOKENmedium3 occurrences

.github/workflows/manifest-check.yml

3 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

4 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/release.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/manifest-check.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.