A personal knowledge and memory system over an Obsidian vault. Vector seeds, graph expansion, LLM synthesis — the kind of memory companion that grows with you over time.
Point it at your vault, ask it a question, and it answers from your own notes with citations — following both semantic similarity and the wikilinks you already drew by hand. Left running, it also writes back: summarizing notes, proposing links, and distilling themed memory files about who you are.
Apache-2.0 · Python 3.11–3.14 · runs entirely on your machine, no external services to install.
→ Start at the documentation index.
| Page | What's in it |
|---|---|
| Getting Started | Step-by-step install (Windows 11, Linux, macOS), where your API key is stored, first ingest, first query |
| Architecture | The data flow from a .md file to a cited answer |
| CLI Reference | Every daemon subcommand and flag |
| Configuration | Every key in config.yaml, path anchoring, env overrides |
| Background Agents | The writeback jobs, the safety rules, scheduling |
| Roadmap | Shipped, next, and deliberately deferred |
| Development | Test layout, linting, contributing |
The docs also build as a site: mkdocs serve, then open http://127.0.0.1:8000.
My Daemon builds two complementary representations of your vault and queries them together:
| Layer | What it stores | What it's good at |
|---|---|---|
| Vector store (Qdrant, embedded) | Dense + sparse embeddings of every chunk | Paraphrased and conceptual recall; exact-token recall via BM42 |
| Graph (NetworkX) | Note ↔ note (wikilinks) and note ↔ tag edges | Following the structure you already gave your notes |
A query embeds, finds seed chunks by hybrid dense+sparse fusion, BFS-expands those seeds through the graph with distance decay, ranks and trims to a token budget, then sends the result to Claude with a "you are this person's daemon" prompt. Every query and the candidates it surfaced are logged to SQLite, so a later phase can learn which sources you actually found useful.
Architecture walks the whole path with the real function names.
Full instructions — including the prerequisites and what to do when something goes wrong — are in Getting Started.
Windows 11 — one file. Download install-my-daemon.bat and double-click it. It finds Python (offering to install it if missing), fetches the app, adds My Daemon to your Start Menu, and opens the Setup window so you can pick your vault and enter your API key. Nothing else to download, no git, no folder to choose.
SmartScreen will say "Windows protected your PC" — that means the file isn't code-signed, not that it's unsafe. More info → Run anyway.
Linux / macOS — from source.
git clone https://github.com/evangress/my-daemon.git && cd my-daemon
python setup.py # creates .venv, installs deps, copies config templates
daemon setup # pick the vault, store the API key
daemon doctor
daemon ingest -v
daemon query "what was I thinking about last week"Developers on Windows want the same from-source path — see Install from source.
daemon ingest is incremental — re-running only re-embeds notes you've changed. daemon doctor is the thing to run whenever something looks wrong; it checks config, vault, vector store, API key, model cache, database schema, and graph, and tells you which one is unhappy.
There is nothing to install alongside it and no server to start: the vector store runs embedded, in-process. (A standalone Qdrant server is supported for large vaults or concurrent CLI+GUI access — see Getting Started.)
Synthesis calls Claude, so you need an Anthropic API key. It is resolved from three places, first hit wins:
| # | Source | Encrypted at rest | Set it with |
|---|---|---|---|
| 1 | ANTHROPIC_API_KEY env var |
no | export / $env: — CI, containers, headless |
| 2 | OS credential store | yes | daemon setup — Windows Credential Manager, macOS Keychain, Linux Secret Service |
| 3 | .env beside config.yaml |
no — plaintext | legacy only, kept so older installs keep working |
daemon setup writes to layer 2 and nowhere else; a key found in a legacy .env is migrated and the plaintext line stripped. The key is never written to config.yaml (which is therefore safe to commit) and is never printed — daemon doctor reports only which layer supplied it, and warns when that layer is a plaintext file.
Retrieval itself needs no key at all: daemon search, daemon ingest, and daemon query --no-llm all work without one.
daemon chat opens a native desktop window (pywebview), or --no-native for a browser tab at http://127.0.0.1:8765. Per-OS one-action launches — launch-gui.vbs on Windows, my-daemon.desktop on Linux, launch-gui.command on macOS — are generated by setup.py. Details and flags: GUI module.
Three optional jobs let the daemon shape the vault rather than only read it. All are gated behind agent.enabled: true and refuse to write until you flip it:
daemon extract— appends an## Agent Notessection (summary, themes, open questions) to recently-changed notes, between idempotent sentinels.daemon link— applies high-confidence wikilinks and tags; queues borderline ones toAgent/link-suggestions-*.mdfor review.daemon reflect— maintains themed memory files in<vault>/Agent/distilling who you are over time.
Every write is snapshotted first, the daemon never touches its own Agent/ folder, and a daemon: ignore frontmatter key opts any note out entirely. The full safety discipline and scheduling guidance is in Background Agents — read it before enabling anything.
src/my_daemon/
├── cli.py # `daemon` Typer entry point
├── config.py # layered Pydantic settings (defaults → yaml → env)
├── secrets.py # API key resolution: env → OS credential store → legacy .env
├── paths.py # config search order and platform state/log directories
├── doctor.py # `daemon doctor` — the 8 preflight checks
├── supervisor.py # `daemon run` — the long-lived foreground process
├── models.py # Note, Chunk, RetrievedChunk, FeedbackEvent
├── vault/ # reader, parser, chunker — markdown → Chunks
├── embeddings/ # sentence-transformers wrapper
├── stores/ # Qdrant vectors, NetworkX graph, SQLite feedback
├── retrieval/ # seed → expand → orchestrate
├── analysis/ # structural + theme analysis over frozen snapshots
├── llm/ # Anthropic client + synthesis prompts
├── gui/ # NiceGUI chat window, Tkinter setup window
├── integration/ # DaemonCore — the one adapter every front end shares
├── hermes/ # Hermes memory-provider plugin
└── pipeline/ # ingest_vault, QueryEngine
install-my-daemon.bat # the one file a Windows user downloads
scripts/bootstrap.py # what it runs: fetch, unpack, install, shortcuts
setup.py # from-source bootstrap (venv, deps, launchers)
librarian/ # the Obsidian Librarian — a separate process that
# shapes the vault, built on my_daemon as a library
docs-source/ # the documentation in this README's index above
tests/ # 677 tests, no external services required
Design and planning documents live at the repo root: MY-DAEMON-VISION.md (intent), MY-DAEMON-RESEARCH.md (prior art), MY-DAEMON-SCAFFOLD.md (full design and phasing), PROJECT_MANAGEMENT.md (milestones, known bugs, running to-do), and THEME.md (the visual language).
My Daemon can act as the memory and dream layer for the Hermes agent (MIT) — Hermes acts; My Daemon remembers and dreams. Ambient cited recall before every turn, automatic injection of the daemon's latest observer letter, and turn-by-turn capture, all off by default. See the integration guide and PLAN-HERMES.md; preflight with daemon hermes doctor.
v0.1. The end-to-end pipeline — ingest → retrieve → synthesize → log — works against real vaults, and the daemon envelope around it (config resolution, atomic state writes, preflight checks, backup/restore, supervisor, scheduling) is in place. Background-agent writeback is wired up but gated off until you confirm the thresholds with --dry-run.
Adaptive edge weighting, nightly consolidation, and the observer LLM have shipped as M1–M4; multi-embedding spaces, an Obsidian plugin with live file watching, and local-LLM synthesis remain deferred. See the roadmap for the current picture.
uv sync --all-extras # or: pip install -e .[dev]
pytest -q # 663 tests, no external services needed
ruff check . && ruff format --check .
mypy src/my_daemonCI runs exactly these four on every push. More in Development.
Apache-2.0 — see LICENSE. Also available under a commercial license; see COMMERCIAL-LICENSE.md.
A triple pun. Philip Pullman's daemon, the external soul-companion in His Dark Materials that knows its human completely. Socrates' daimonion, the inner advisory voice. And the Unix sense — a background process that runs quietly on your behalf.
The intent is all three: not a tool you operate, but a companion that grows with you — sometimes whispering, sometimes working quietly while you sleep.