vicky

Vicky

Demand-driven knowledge base MCP server. Auto-enriches answers when gaps detected. Drives Obsidian + Dataview for live KB views.

What it does

• Local KB of sources + conclusions, queried by your agent
• Detects gaps in your question, auto-enqueues research
• Processes the queue when you ask, enriches conclusions
• Exposes Dataview (DQL) directly to the agent for arbitrary KB queries
• Ships an Obsidian vault preset (Dataview pre-configured)

Requirements

• Node.js 18+
• Obsidian (for dashboard / dql tools)
• Any MCP-capable agent (Claude Code, Claude API, Cursor, etc.)
• LLM API key for graphify's semantic pass (see LLM API key below)

graphify ships as a bundled dependency (graphifyy on npm). npm install pulls it in — no external install needed. Vicky resolves the local binary at runtime.

Install

Claude Code (plugin)

/plugin marketplace add yesitsfebreeze/vicky
/plugin install vicky@vicky

Registers the MCP server, hooks init() to SessionStart, and exposes the vicky skill. First session scaffolds the Obsidian preset (.obsidian/ with Dataview + graph) at the project root and vicky/{sources,conclusions,pending,graphs,Dashboard.md,WORKFLOW.md} beside it. The project root is the Obsidian vault.

Any other MCP-capable agent

git clone https://github.com/yesitsfebreeze/vicky ~/vicky
cd ~/vicky/src && npm install && npm run build

Register the MCP server pointing at ~/vicky/dist/index.js. Example .mcp.json:

{
  "mcpServers": {
    "vicky": {
      "command": "node",
      "args": ["~/vicky/dist/index.js"]
    }
  }
}

Restart the agent. First call triggers init(). Open the project root in Obsidian — the .obsidian/ preset enables Dataview + graph settings. (Plugins must be installed via the Community Plugins UI on first run; the preset only declares which are enabled.)

Update

cd ~/vicky && git pull && cd src && npm install && npm run build

Restart the agent so the MCP server reloads. vicky/ is yours — init() never overwrites existing files.

Tools (MCP)

Tool	Purpose
research-gap "q"	Query KB; auto-enqueue if gap
research	Drain pending queue → conclusion stubs
query "q"	Direct KB lookup (focus-biased)
remember "title"	Save findings to vault
enqueue "q"	Manual queue add
dashboard	KB report via Obsidian + Dataview
dql "<query>"	Run arbitrary DQL. query="help" for syntax
relink	Rebuild link graph
web-search	Web research helper

Layout

~/vicky/                     # plugin root (clone target)
├── .claude-plugin/          # plugin manifest
├── hooks/                   # SessionStart init hook
├── dist/                    # bundled MCP server (CI-built, committed)
├── scaffold/                # template tree mirroring project root (copied to . on init)
├── skills/                  # Claude Code skills
├── src/                     # source + build (node_modules lives here)
│   ├── package.json
│   ├── build.js
│   ├── index.js, init.js, dashboard.js, ...
│   └── tools/
└── README.md                # this file

<your project>/             # ← Obsidian vault (open this in Obsidian)
├── .obsidian/              # Obsidian preset (Dataview + graph + plugin list)
└── vicky/                  # created by init() in each project
    ├── sources/             # external research, papers
    ├── conclusions/         # synthesized knowledge
    ├── pending/             # queued research questions
    ├── .graphify/           # graphify state — graph.json (semantic, BFS target)
    ├── graphs/              # Dataview-queryable wiki: vicky.md + cluster pages
    ├── .graphifyignore      # extract scope (excludes pending/, graphs/, etc.)
    ├── WORKFLOW.md          # focus, rules, routing (edit to steer Vicky)
    └── Dashboard.md         # live Dataview views

WORKFLOW.md

Single source of truth for runtime behavior. Edit frontmatter:

active_focus: [perf, nanite]      # bias query results + Dashboard
priority_tags: [blocker]
auto_enqueue: true                # false = gaps don't auto-queue
default_workflow: default         # default | deep-dive | triage

Sections: Focus, Active Rules, Workflows, Routing (regex → workflow). Re-read on every tool call.

Dataview / DQL

Vicky drives obsidian.exe eval to run real DQL inside Obsidian's Dataview plugin. Same engine as the human-facing Dashboard.md, no separate renderer.

Full DQL reference: https://blacksmithgu.github.io/obsidian-dataview/queries/structure/

Top queries the agent uses:

# Hubs (most-referenced)
TABLE WITHOUT ID file.link AS Node, length(file.inlinks) AS Inlinks
FROM "conclusions" OR "sources"
WHERE length(file.inlinks) > 0
SORT length(file.inlinks) DESC LIMIT 20