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 vicky/{sources,conclusions,pending,graphs} plus the Obsidian preset (.obsidian/, Dashboard.md, WORKFLOW.md, folder indexes).

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 vicky/ in Obsidian and enable Dataview (the preset auto-installs it on first open).

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)
├── obsidian/                # template scaffolded into vicky/ 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>/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/, .obsidian/, etc.)
├── .obsidian/               # Obsidian vault config (Dataview enabled)
├── 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

# Pending queue, priority-sorted
TABLE WITHOUT ID file.link AS Q, priority, requested_by, date
FROM "pending"
WHERE status = "pending"
SORT choice(priority="high",0,choice(priority="med",1,2)) ASC