Skip to content

richfrem/agent-plugins-skills / plugins/agent-memory/.apm/skills/managing-obsidian-vaults

managing-obsidian-vaults

Verified

Interactive vault, wiki and Super-RAG setup in the main conversation. Use for "set up my wiki", "initialize the full knowledge stack" or combined RLM/vector/wiki setup. Manage Obsidian vaults and LLM wikis: initialize vaults, author Markdown and wikilinks, safely edit notes and Bases, create Canvas diagrams, traverse graphs, build concept wikis, distill summary/bullets/deep layers, query and lint knowledge.

FileKindSize
SKILL.mdskill md5.9 KB
assets/templates/config.yaml.templateother556 B
assets/templates/raw-sources.json.exampleother862 B
assets/templates/wiki-node.template.mdmarkdown410 B
evals/README.mdmarkdown569 B
evals/evals.jsonconfig23.4 KB
evals/legacy/obsidian-bases-manager/evals.jsonconfig692 B
evals/legacy/obsidian-bases-manager/results.tsvother301 B
evals/legacy/obsidian-canvas-architect/evals.jsonconfig731 B
evals/legacy/obsidian-canvas-architect/results.tsvother301 B
evals/legacy/obsidian-graph-traversal/evals.jsonconfig706 B
evals/legacy/obsidian-graph-traversal/results.tsvother301 B
evals/legacy/obsidian-init/evals.jsonconfig667 B
evals/legacy/obsidian-init/results.tsvother301 B
evals/legacy/obsidian-markdown-mastery/evals.jsonconfig652 B
evals/legacy/obsidian-markdown-mastery/results.tsvother301 B
evals/legacy/obsidian-query-agent/evals.jsonconfig767 B
evals/legacy/obsidian-rlm-distiller/evals.jsonconfig685 B
evals/legacy/obsidian-vault-crud/evals.jsonconfig638 B
evals/legacy/obsidian-vault-crud/results.tsvother301 B
evals/legacy/obsidian-wiki-builder/evals.jsonconfig732 B
evals/legacy/obsidian-wiki-linter/evals.jsonconfig1.5 KB
evals/results.tsvother73 B
evals/task-success.jsonconfig3.5 KB
references/acceptance-criteria.mdmarkdown2.9 KB
references/architecture-background.mdmarkdown2.8 KB
references/dependencies.mdmarkdown1.7 KB
references/interactive-setup.mdmarkdown7.0 KB
references/interactive-stack-setup.mdmarkdown5.6 KB
references/kepano-analysis-summary.mdmarkdown1.7 KB
references/obsidian-bases-manager-acceptance-criteria.mdmarkdown628 B
references/obsidian-bases-manager-fallback-tree.mdmarkdown787 B
references/obsidian-bases-manager.mdmarkdown2.1 KB
references/obsidian-canvas-architect-acceptance-criteria.mdmarkdown645 B
references/obsidian-canvas-architect-fallback-tree.mdmarkdown836 B
references/obsidian-canvas-architect.mdmarkdown1.9 KB
references/obsidian-graph-traversal-acceptance-criteria.mdmarkdown690 B
references/obsidian-graph-traversal-fallback-tree.mdmarkdown877 B
references/obsidian-graph-traversal.mdmarkdown2.2 KB
references/obsidian-init-acceptance-criteria.mdmarkdown650 B
references/obsidian-init-fallback-tree.mdmarkdown1.1 KB
references/obsidian-init.mdmarkdown2.0 KB
references/obsidian-markdown-mastery-acceptance-criteria.mdmarkdown700 B
references/obsidian-markdown-mastery-fallback-tree.mdmarkdown889 B
references/obsidian-markdown-mastery.mdmarkdown2.2 KB
references/obsidian-query-agent.mdmarkdown1.8 KB
references/obsidian-rlm-distiller.mdmarkdown1.8 KB
references/obsidian-vault-crud-acceptance-criteria.mdmarkdown833 B
references/obsidian-vault-crud-fallback-tree.mdmarkdown1.1 KB
references/obsidian-vault-crud.mdmarkdown2.2 KB
references/obsidian-vault-onboarding-guide.mdmarkdown3.7 KB
references/obsidian-wiki-builder.mdmarkdown1.8 KB
references/obsidian-wiki-linter.mdmarkdown1.7 KB
references/resource-index.mdmarkdown4.3 KB
references/safety-learnings.mdmarkdown2.7 KB
references/wiki-builder-guide.mdmarkdown2.7 KB
references/wiki-distillation-guide.mdmarkdown1.7 KB
references/wiki-linting-guide.mdmarkdown2.1 KB
references/wiki-query-guide.mdmarkdown2.1 KB
requirements.inother32 B
requirements.txtmanifest463 B
scripts/audit.pyscript9.0 KB
scripts/bases_ops.pyscript7.8 KB
scripts/canvas_gen.pyscript7.9 KB
scripts/canvas_ops.pyscript11.5 KB
scripts/concept_extractor.pyscript10.2 KB
scripts/constants.pyscript908 B
scripts/distill_wiki.pyscript12.9 KB
scripts/graph_ops.pyscript11.7 KB
scripts/ingest.pyscript8.3 KB
scripts/init_vault.pyscript5.7 KB
scripts/lint_wiki.pyscript9.3 KB
scripts/obsidian-parser/parser.pyscript6.5 KB
scripts/obsidian-parser/tests/test_parser.pyscript4.1 KB
scripts/query_wiki.pyscript21.3 KB
scripts/raw_manifest.pyscript14.3 KB
scripts/vault_ops.pyscript13.4 KB
scripts/wiki_builder.pyscript14.3 KB

scripts/vault_ops.py

View on GitHub
"""
vault_ops.py (CLI)
=====================================

Purpose:
    Safe Create/Read/Update/Append operations for Obsidian Vault notes.
    Implements atomic writes, advisory locking, concurrent edit detection,
    and lossless YAML frontmatter handling.

Layer: Core Operations

Usage Examples:
    pythonult_ops.py read --file note.md
    pythonult_ops.py create --file note.md --content "Hello"

Supported Object Types:
    - .md (Markdown notes with Obsidian syntax)

CLI Arguments:
    Subcommands: read, create, update, append. Run with --help for details.

Input Files:
    - .md files.

Output:
    - JSON results or status messages.

Key Functions:
    read_note(): Read a note and return its frontmatter and body.
    create_note(): Create a new note with optional frontmatter.
    update_note(): Update a note's body, preserving frontmatter.
    append_to_note(): Append content to an existing note.

Script Dependencies:
    os, sys, json, argparse, tempfile, subprocess, pathlib, typing, ruamel.yaml

Consumed by:
    - obsidian-vault-crud skill
"""
import os
import sys
import json
import argparse
import tempfile
from constants import consumer_project_root
import subprocess
from pathlib import Path
from typing import Optional, Dict, Any, Tuple

# --- T029: Lossless YAML (ruamel.yaml preferred, fallback warning) ---
try:
    from ruamel.yaml import YAML
    _yaml = YAML()
    _yaml.preserve_quotes = True
    _yaml.default_flow_style = False
    HAS_RUAMEL = True
except ImportError:
    HAS_RUAMEL = False
    print("WARNING: ruamel.yaml not installed. Frontmatter operations will be unavailable.", file=sys.stderr)
    print("Install with: pip install ruamel.yaml", file=sys.stderr)

# ---------------------------------------------------------------------------
# Environment
# ---------------------------------------------------------------------------
VAULT_ROOT = Path(os.environ.get("VAULT_PATH", os.environ.get("OBSIDIAN_VAULT_PATH", str(consumer_project_root()))))
LOCK_FILE = VAULT_ROOT / ".agent-lock"


# ---------------------------------------------------------------------------
# T027: Advisory Lock Protocol
# ---------------------------------------------------------------------------
class AgentLock:
    """
    Advisory lock for agent-vs-agent write coordination.
    Creates `.agent-lock` at the vault root before write batches.
    """

    def __init__(self, vault_root: Path = VAULT_ROOT) -> None:
        """Initialize the lock, targeting {vault_root}/.agent-lock."""
        self.lock_path = vault_root / ".agent-lock"
        self._acquired = False

    def acquire(self, agent_name: str = "Antigravity") -> bool:
        """Acquire the advisory lock. Returns False if already locked."""
        if self.lock_path.exists():
            try:
                lock_info = json.loads(self.lock_path.read_text())
                print(f"WARNING: Vault is locked by agent '{lock_info.get('agent', 'unknown')}' "
                      f"since {lock_info.get('timestamp', 'unknown')}", file=sys.stderr)
            except (json.JSONDecodeError, OSError):
                print("WARNING: Stale lock file detected.", file=sys.stderr)
            return False

        lock_data = {
            "agent": agent_name,
            "pid": os.getpid(),
            "timestamp": _now_iso()
        }
        self.lock_path.write_text(json.dumps(lock_data, indent=2))
        self._acquired = True
        return True

    def release(self) -> None:
        """Release the advisory lock."""
        if self._acquired and self.lock_path.exists():
            self.lock_path.unlink()
            self._acquired = False

    def __enter__(self) -> "AgentLock":
        """Acquire the lock on context-manager entry; raise if another agent already holds it."""
        if not self.acquire():
            raise RuntimeError("Failed to acquire agent lock. Another agent is writing.")
        return self

    def __exit__(self, exc_type: Optional[type], exc_val: Optional[BaseException], exc_tb: Optional[Any]) -> bool:
        """Release the lock on context-manager exit. Never suppresses exceptions."""
        self.release()
        return False


# ---------------------------------------------------------------------------
# T028: Concurrent Edit Detection (mtime guard)
# ---------------------------------------------------------------------------
def capture_mtime(filepath: Path) -> float:
    """Capture the modification time of a file."""
    return filepath.stat().st_mtime


def check_mtime_unchanged(filepath: Path, original_mtime: float) -> bool:
    """
    Returns True if the file's mtime has NOT changed since we read it.
    If it changed, another process (human or Obsidian) edited the file.
    """
    current_mtime = filepath.stat().st_mtime
    return current_mtime == original_mtime


# ---------------------------------------------------------------------------
# T026: Atomic Write Protocol
# ---------------------------------------------------------------------------
def atomic_write(filepath: Path, content: str) -> None:
    """
    Write content to a file atomically using POSIX os.rename().
    1. Write to <filepath>.agent-tmp
    2. os.rename() to <filepath> (atomic on POSIX)
    3. Cleanup on failure
    """
    tmp_path = filepath.parent / f"{filepath.name}.agent-tmp"
    try:
        tmp_path.write_text(content, encoding='utf-8')
        os.rename(str(tmp_path), str(filepath))
    except Exception:
        # Cleanup the temp file if rename failed
        if tmp_path.exists():
            tmp_path.unlink()
        raise


# ---------------------------------------------------------------------------
# T029: Frontmatter Handling (ruamel.yaml)
# ---------------------------------------------------------------------------
def split_frontmatter(content: str) -> Tuple[Optional[str], str]:
    """
    Split a markdown file into frontmatter (YAML) and body.
    Returns (frontmatter_str, body) where frontmatter_str may be None.
    """
    if not content.startswith('---'):
        return None, content

    # Find the closing ---
    end_idx = content.find('---', 3)
    if end_idx == -1:
        return None, content

    # Find the actual end (after the ---)
    end_of_frontmatter = end_idx + 3
    # Skip optional newline after closing ---
    if end_of_frontmatter < len(content) and content[end_of_frontmatter] == '\n':
        end_of_frontmatter += 1

    frontmatter_str = content[3:end_idx].strip()
    body = content[end_of_frontmatter:]

    return frontmatter_str, body


def parse_frontmatter(frontmatter_str: str) -> Dict[str, Any]:
    """Parse YAML frontmatter string using ruamel.yaml for lossless round-tripping."""
    if not HAS_RUAMEL:
        raise RuntimeError("ruamel.yaml is required for frontmatter operations. Install with: pip install ruamel.yaml")

    from io import StringIO
    return dict(_yaml.load(StringIO(frontmatter_str)) or {})


def render_frontmatter(data: Dict[str, Any]) -> str:
    """Render frontmatter dict back to YAML string, preserving formatting."""
    if not HAS_RUAMEL:
        raise RuntimeError("ruamel.yaml is required for frontmatter operations.")

    from io import StringIO
    stream = StringIO()
    _yaml.dump(data, stream)
    yaml_text = stream.getvalue()
    return f"---\n{yaml_text}---\n"


# ---------------------------------------------------------------------------
# CRUD Operations
# ---------------------------------------------------------------------------
def read_note(filepath: Path) -> Dict[str, Any]:
    """Read a note and return its frontmatter and body."""
    if not filepath.exists():
        return {"error": f"File not found: {filepath}"}

    mtime = capture_mtime(filepath)
    content = filepath.read_text(encoding='utf-8')
    fm_str, body = split_frontmatter(content)

    result = {
        "file": str(filepath),
        "mtime": mtime,
        "body": body,
    }

    if fm_str and HAS_RUAMEL:
        try:
            result["frontmatter"] = parse_frontmatter(fm_str)
        except Exception as e:
            result["frontmatter_error"] = str(e)
            result["frontmatter_raw"] = fm_str

    return result


def create_note(filepath: Path, content: str, frontmatter: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
    """Create a new note with optional frontmatter."""
    if filepath.exists():
        return {"error": f"File already exists: {filepath}. Use 'update' instead."}

    # Ensure parent directory exists
    filepath.parent.mkdir(parents=True, exist_ok=True)

    full_content = ""
    if frontmatter:
        full_content = render_frontmatter(frontmatter)
    full_content += content

    with AgentLock():
        atomic_write(filepath, full_content)

    return {"status": "created", "file": str(filepath)}


def update_note(filepath: Path, content: str) -> Dict[str, Any]:
    """Update a note's body, preserving frontmatter. Aborts if concurrent edit detected."""
    if not filepath.exists():
        return {"error": f"File not found: {filepath}. Use 'create' instead."}

    original_mtime = capture_mtime(filepath)
    original_content = filepath.read_text(encoding='utf-8')
    fm_str, _ = split_frontmatter(original_content)

    # Reconstruct with preserved frontmatter
    if fm_str:
        new_content = f"---\n{fm_str}\n---\n{content}"
    else:
        new_content = content

    with AgentLock():
        # T028: Check for concurrent edits before writing
        if not check_mtime_unchanged(filepath, original_mtime):
            return {"error": "CONCURRENT_EDIT_DETECTED", "file": str(filepath),
                    "message": "File was modified by another process since we read it. Aborting to prevent data loss."}
        atomic_write(filepath, new_content)

    return {"status": "updated", "file": str(filepath)}


def append_to_note(filepath: Path, content: str) -> Dict[str, Any]:
    """Append content to an existing note."""
    if not filepath.exists():
        return {"error": f"File not found: {filepath}"}

    original_mtime = capture_mtime(filepath)
    original_content = filepath.read_text(encoding='utf-8')

    new_content = original_content.rstrip('\n') + '\n\n' + content + '\n'

    with AgentLock():
        if not check_mtime_unchanged(filepath, original_mtime):
            return {"error": "CONCURRENT_EDIT_DETECTED", "file": str(filepath),
                    "message": "File was modified by another process since we read it. Aborting."}
        atomic_write(filepath, new_content)

    return {"status": "appended", "file": str(filepath)}


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _now_iso() -> str:
    """Return current UTC time in ISO format."""
    from datetime import datetime, timezone
    return datetime.now(timezone.utc).isoformat()


# ---------------------------------------------------------------------------
# CLI Entry Point
# ---------------------------------------------------------------------------
def _build_arg_parser() -> argparse.ArgumentParser:
    """Build the CLI argument parser with read/create/update/append subcommands."""
    parser = argparse.ArgumentParser(description="Obsidian Vault CRUD Operations")
    subparsers = parser.add_subparsers(dest='command', help='Commands')

    # Read
    read_p = subparsers.add_parser('read', help='Read a note')
    read_p.add_argument('--file', required=True, help='Path to note')

    # Create
    create_p = subparsers.add_parser('create', help='Create a new note')
    create_p.add_argument('--file', required=True, help='Path for new note')
    create_p.add_argument('--content', required=True, help='Note body content')
    create_p.add_argument('--frontmatter', nargs='*', help='Key=value pairs for frontmatter')

    # Update
    update_p = subparsers.add_parser('update', help='Update a note body')
    update_p.add_argument('--file', required=True, help='Path to note')
    update_p.add_argument('--content', required=True, help='New body content')

    # Append
    append_p = subparsers.add_parser('append', help='Append to a note')
    append_p.add_argument('--file', required=True, help='Path to note')
    append_p.add_argument('--content', required=True, help='Content to append')

    return parser


def _parse_frontmatter_kv(pairs: Optional[list]) -> Optional[Dict[str, Any]]:
    """Parse a list of 'key=value' strings into a frontmatter dict, or None if pairs is empty."""
    if not pairs:
        return None
    fm: Dict[str, Any] = {}
    for kv in pairs:
        k, v = kv.split('=', 1)
        fm[k] = v
    return fm


def main() -> None:
    """Parse CLI subcommand args and dispatch to read/create/update/append note operations."""
    parser = _build_arg_parser()
    args = parser.parse_args()

    if args.command == 'read':
        result = read_note(Path(args.file))
        print(json.dumps(result, indent=2, default=str))

    elif args.command == 'create':
        fm = _parse_frontmatter_kv(args.frontmatter)
        content = args.content.replace('\\n', '\n')
        result = create_note(Path(args.file), content, fm)
        print(json.dumps(result, indent=2))

    elif args.command == 'update':
        content = args.content.replace('\\n', '\n')
        result = update_note(Path(args.file), content)
        print(json.dumps(result, indent=2))

    elif args.command == 'append':
        content = args.content.replace('\\n', '\n')
        result = append_to_note(Path(args.file), content)
        print(json.dumps(result, indent=2))

    else:
        parser.print_help()


if __name__ == '__main__':
    main()
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall