obsidian-cli-memory-bank

Category: Docs & Knowledge | Uploader: georgeantonopoulos | Downloads: 0 | Version: v1.0（Latest）

Build and maintain project-specific Obsidian knowledge bases through Obsidian CLI. Use when an agent needs to (1) ask once for a vault and persist it for a workspace, (2) capture prompt/run context as structured Markdown notes, (3) auto-link notes with wikilinks for strong backlink coverage, (4) retrieve context quickly via Obsidian CLI search/read commands, or (5) audit graph hygiene with unresolved/orphan/dead-end link checks.

Changelog: Source: GitHub https://github.com/georgeantonopoulos/obsidian-cli-memory-bank-skill

Directory Structure

Current level: Root

📁 agents/
- 📄 openai.yaml 206 B
📁 claude-code/
- 📁 hooks/
  - 📄 obsidian_memory_sync_hook.py 3.3 KB
  - 📄 obsidian_poststop_hook.py 2.7 KB
  - 📄 obsidian_precompact_hook.py 2.7 KB
  - 📄 obsidian_preprompt_hook.py 4.7 KB
  - 📄 obsidian_sessionstart_hook.py 2.1 KB
- 📄 INSTALL.md 3.6 KB
- 📄 SKILL.md 5.4 KB
📁 references/
- 📄 obsidian-cli-patterns.md 1.2 KB
📁 scripts/
- 📁 tests/
  - 📄 __init__.py 33 B
  - 📄 test_antigravity_notify_hook.py 816 B
  - 📄 test_claude_notify_hook.py 827 B
  - 📄 test_codex_notify_hook.py 1.1 KB
  - 📄 test_cursor_notify_hook.py 2.0 KB
  - 📄 test_hook_common.py 4.4 KB
  - 📄 test_obsidian_memory.py 5.6 KB
- 📄 __init__.py 33 B
- 📄 antigravity_notify_hook.py 4.4 KB
- 📄 claude_notify_hook.py 4.6 KB
- 📄 codex_notify_hook.py 2.7 KB
- 📄 cursor_notify_hook.py 6.2 KB
- 📄 hook_common.py 6.1 KB
- 📄 install_codex_notify_hook.sh 2.3 KB
- 📄 obsidian_memory.py 28.2 KB
📄 .gitignore 179 B
📄 INSTALL.md 2.2 KB
📄 pyproject.toml 1.1 KB
📄 README.md 8.6 KB
📄 SKILL.md 6.5 KB
📄 uv.lock 145 B

SKILL.md

---
name: obsidian-cli-memory-bank
description: Build and maintain project-specific Obsidian knowledge bases through Obsidian CLI. Use when an agent needs to (1) ask once for a vault and persist it for a workspace, (2) capture prompt/run context as structured Markdown notes, (3) auto-link notes with wikilinks for strong backlink coverage, (4) retrieve context quickly via Obsidian CLI search/read commands, or (5) audit graph hygiene with unresolved/orphan/dead-end link checks.
---

# Obsidian Cli Memory Bank

## Overview

Use this skill to maintain a per-project "memory bank" inside Obsidian with consistent note structure, dense wikilinking, and CLI-first retrieval.
Persist the vault path once, then bootstrap/update project notes on every relevant run.

## Communication Style

- Be friendly and conversational 🙂.
- Use light emojis to keep updates engaging (`✅`, `🧠`, `🔎`, `🛠️`).
- Avoid noisy failure narration when a safe fallback exists (for example missing optional env vars).

## Workflow

Resolve the skill path first. Do **not** assume any one agent runtime path:

```bash
if [ -f "./scripts/obsidian_memory.py" ]; then
  SKILL_DIR="$(pwd)"
elif [ -n "${CODEX_HOME:-}" ] && [ -d "$CODEX_HOME/skills/obsidian-cli-memory-bank" ]; then
  SKILL_DIR="$CODEX_HOME/skills/obsidian-cli-memory-bank"
elif [ -d "$HOME/.codex/skills/obsidian-cli-memory-bank" ]; then
  SKILL_DIR="$HOME/.codex/skills/obsidian-cli-memory-bank"
else
  echo "Need absolute path to obsidian-cli-memory-bank skill directory."
  exit 1
fi
```

Run all helper commands as:

```bash
python3 "$SKILL_DIR/scripts/obsidian_memory.py" <command> ...
```

### 1) Resolve vault first

Run:

```bash
python3 "$SKILL_DIR/scripts/obsidian_memory.py" show-vault
```

If no vault is set for the current workspace:

1. Ask exactly one question: `Which absolute vault path should I use for this project?`
2. Save it:

```bash
python3 "$SKILL_DIR/scripts/obsidian_memory.py" set-vault --vault-path "/absolute/path/to/vault"
```

Use `--workspace "/path/to/project"` when setting or resolving a different workspace than the current directory.

### 2) Bootstrap project memory structure

Create core notes once per project:

```bash
python3 "$SKILL_DIR/scripts/obsidian_memory.py" bootstrap --project "Sequency"
```

Or run the one-command initializer:

```bash
python3 "$SKILL_DIR/scripts/obsidian_memory.py" init-project --project "Sequency" --with-stub
```

This creates:

- `Project Memory/<project-slug>/<Project Home>.md`
- `Project Memory/<project-slug>/MOC.md`
- `Project Memory/<project-slug>/Run Log.md`
- `Project Memory/<project-slug>/Decisions.md`
- `Project Memory/<project-slug>/Open Questions.md`

All seed notes include wikilinks to each other so backlinks are available immediately.

### 3) Record each meaningful run

After a task, add a run note:

```bash
python3 "$SKILL_DIR/scripts/obsidian_memory.py" record-run \
  --project "Sequency" \
  --title "Fix MXF progress regression" \
  --summary "Updated progress to use true frame counts." \
  --prompt "User asked for accurate progress on MXF exports." \
  --actions "Adjusted estimateFrameCount routing in exporter and view model." \
  --decisions "Prefer measured frame counts over duration heuristics." \
  --questions "Confirm behavior for variable-frame-rate MXF corpus." \
  --tags "swift,mxf,bugfix"
```

This creates a timestamped note in `Runs/`, appends it to `Run Log.md`, and links back to project anchor notes.

### 4) Retrieve context before answering

Use CLI retrieval first:

```bash
# search by topic
python3 "$SKILL_DIR/scripts/obsidian_memory.py" search --project "Sequency" --query "MXF fallback routing"

# inspect a key note
python3 "$SKILL_DIR/scripts/obsidian_memory.py" read-note \
  --path "Project Memory/sequency/Decisions.md"
```

### 5) Keep graph hygiene high

Run periodic audits:

```bash
python3 "$SKILL_DIR/scripts/obsidian_memory.py" audit --project "Sequency"
```

This runs:

- `obsidian unresolved counts verbose`
- `obsidian orphans`
- `obsidian deadends`
- `obsidian backlinks path="<project-home-note>" counts`

Automatic behavior: `record-run` triggers auto-audit every N runs (default `5`).
Change cadence:

```bash
python3 "$SKILL_DIR/scripts/obsidian_memory.py" set-audit-frequency --runs 5
```

Set `--runs 0` to disable auto-audit.

### 6) Health-check setup

Run:

```bash
python3 "$SKILL_DIR/scripts/obsidian_memory.py" doctor
```

This validates Obsidian CLI availability, app reachability, workspace-to-vault mapping, and vault write access.

## Persistence Mode

Use this pattern to behave as “always-on” memory:

1. At first action in a session, run `show-vault`; ask user only if missing.
2. At task start, run `search` for key topic terms before proposing changes.
3. At task end, run `record-run` with summary + rationale.
4. Run `audit` periodically (or after major refactors).

### Hook Integration (Optional)

For runtimes that support hook events, adapter scripts automate memory operations at key lifecycle points:

| Lifecycle Point | Purpose | Claude Code | Codex |
|----------------|---------|-------------|-------|
| Session start | Health-check vault connectivity | `SessionStart` | — |
| Before response | Search vault for relevant context | `UserPromptSubmit` | — |
| After response | Log structured run note | `Stop` | `agent-turn-complete` |
| Before compaction | Persist transcript before context compression | `PreCompact` | — |
| After memory write | Mirror MEMORY.md to vault | `PostToolUse` | — |

**Claude Code**: See `claude-code/INSTALL.md` for full setup (5 hooks with settings.json entries).

**Codex**: Install the notify hook:

```bash
chmod +x scripts/install_codex_notify_hook.sh scripts/codex_notify_hook.py
"$SKILL_DIR/scripts/install_codex_notify_hook.sh"
```

**Other runtimes** (Cursor, Antigravity, etc.): Adapt the scripts in `claude-code/hooks/` or `scripts/` to the runtime's hook format. The core pattern is the same — call `obmem` CLI commands at the appropriate lifecycle point.

All hooks silently no-op when no vault is mapped for the current workspace.

## Rules

1. Prefer wikilinks (`[[Note]]`) over plain text references.
2. Link every run note to at least: `[[<Project Home>]]`, `[[MOC]]`, and one topic/decision note.
3. Keep properties at the top of notes (`tags`, `created`, `updated`, `project`, `type`).
4. Use short, stable note titles; avoid duplicate names in the same vault.
5. Capture both outcome and rationale so later retrieval answers "what changed" and "why".

## Resources

- Script entrypoint: `scripts/obsidian_memory.py`
- Reference patterns: `references/obsidian-cli-patterns.md`

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

obsidian-cli-memory-bank

Directory Structure

SKILL.md

Report

Notice