alfred-vault 0.2.1

AI-powered background services for Obsidian vault maintenance

🎩 Alfred

Your Obsidian vault runs itself.

Drop files into your inbox. Alfred structures, links, and organizes everything — automatically.

---

You paste a meeting transcript into inbox/. A few seconds later, Alfred has:

• Created a conversation record with participants, status, and activity log
• Created or updated person records for everyone mentioned
• Filed tasks with assignees and linked them to the right project
• Connected everything with wikilinks so it shows up in the right Obsidian views automatically

You didn't trigger any of this. It just happened.

---

The Problem

Obsidian is powerful, but keeping a vault organized is a full-time job. You end up with orphaned notes, broken links, knowledge trapped inside meeting transcripts, and no clear picture of how your projects actually connect. The more you use it, the more maintenance it demands.

The Fix

Alfred is a set of AI-powered background services — four tools that continuously watch, clean, extract, and connect your vault while you do real work.

Tool	What it does
Curator	Watches inbox/ and turns raw files (emails, transcripts, notes) into structured records
Janitor	Scans for broken links, missing frontmatter, orphaned files — and fixes them
Distiller	Reads your notes and extracts decisions, assumptions, and constraints into an evidence graph
Surveyor	Embeds your vault into vectors, clusters by semantic similarity, and writes relationship tags back

Quickstart

pip install alfred-vault
alfred quickstart          # interactive setup wizard
alfred up                  # start background daemons

That's it. The wizard handles vault path, agent backend, and directory scaffolding.

Prerequisites: Python 3.11+ and an AI agent on PATH. Default is Claude Code. Also supports Zo Computer (HTTP) and OpenClaw.

How It Works

Curator — Inbox → Structure

A new file appears in inbox/. Curator reads it, passes it to your AI agent with full vault context, and the agent creates whatever records the content calls for — conversations, people, tasks — all linked together.

Janitor — Entropy → Order

Periodically sweeps every file for structural problems: broken wikilinks, invalid frontmatter, orphaned files, stub records. In fix mode, hands the issues to the AI agent to repair automatically.

Distiller — Notes → Knowledge

Reads operational records (conversations, session logs, project notes) and surfaces latent knowledge worth extracting. Creates epistemic records: assumptions with confidence levels, decisions with rationale, constraints, contradictions, and syntheses. These form an evidence graph that evolves with your vault.

Surveyor — Isolation → Connection

Embeds vault content into vectors (Ollama locally or OpenAI-compatible API), clusters with HDBSCAN + Leiden community detection, asks an LLM to label the clusters, and writes relationship tags and wikilinks back into files. Three notes about the same theme that you never connected? Surveyor finds them.

Install

# Base (curator + janitor + distiller)
pip install alfred-vault

# Full (adds surveyor — requires Ollama + OpenRouter)
pip install "alfred-vault[all]"

# From source
git clone https://github.com/ssdavidai/alfred.git
cd alfred && pip install -e ".[all]"

Agent Backends

Backend	Type	Setup
Claude Code (default)	Subprocess	Install Claude Code, claude on PATH
Zo Computer	HTTP API	Set ZO_API_KEY in .env
OpenClaw	Subprocess	Install OpenClaw, openclaw on PATH

Set agent.backend in config.yaml to claude, zo, or openclaw.

Vault Structure

Structured Markdown with YAML frontmatter. 20 record types across three categories:

Category	Types
Operational	project, task, session, conversation, input, note, process, run, event, thread
Entity	person, org, location, account, asset
Epistemic	assumption, decision, constraint, contradiction, synthesis

Records link via [[wikilinks]] — open any project page and you'll see live tables of tasks, conversations, and people, populated automatically.

CLI Reference

# Daemons
alfred up                              # start all (background)
alfred up --foreground                 # attached mode (dev/debug)
alfred up --only curator,janitor       # start specific tools
alfred down                            # stop
alfred status                          # overview

# Individual tools
alfred curator                         # curator daemon (foreground)
alfred janitor scan                    # scan + report
alfred janitor fix                     # scan + AI fix
alfred janitor watch                   # periodic sweep daemon
alfred distiller scan                  # find candidates
alfred distiller run                   # scan + extract
alfred distiller watch                 # periodic daemon
alfred surveyor                        # full pipeline

# Vault operations
alfred vault create <type> <name>      # create record
alfred vault read <path>               # read record
alfred vault edit <path>               # edit record
alfred vault list [type]               # list records

# External commands with vault context
alfred exec -- <command>               # injects ALFRED_VAULT_PATH
alfred exec --scope curator -- <cmd>   # also sets ALFRED_VAULT_SCOPE

Configuration

alfred quickstart                      # recommended: interactive setup
# — or —
cp config.yaml.example config.yaml
cp .env.example .env

config.yaml has sections for vault, agent, logging, and each tool. Supports ${VAR} environment variable substitution. See config.yaml.example for all options.

Documentation

Full documentation is available in docs/ and on the GitHub Wiki:

• Installation
• Configuration
• CLI Commands
• Vault Schema
• Curator | Janitor | Distiller | Surveyor
• Live Dashboard
• Architecture
• Agent Backends
• User Profile

Contributing

Alfred is early-stage and actively developed. Issues, PRs, and ideas are welcome.

License

MIT

Built with ❤️ by David Szabo-Stuban -> ScreenlessDad.com