Docs
Getting from nothing to a searchable memory your assistant can read.
Early access. These steps describe the Windows desktop build and the hosted replica. Both are changing weekly; if something here does not match what you see, the app is right and this page is stale — tell us at hello@varven.net.
1. Install
Download the Windows installer and run it. On first launch Varven asks for two things:
- A vault folder. Any folder. If you already keep Markdown notes, point it there — Varven reads what is already present.
- Permission to run a local model. Varven ships a small language model that does tagging and summarising on your own hardware.
If you have an NVIDIA GPU it will be used automatically. Without one, Varven falls back to CPU: slower, but it works and it will not silently fail.
2. Check your vault
Before the first sync, run the inspector. It reads your vault, reports how it maps onto what the cloud expects, and sends nothing.
python agent/sync_agent.py --vault "C:\path\to\vault" --inspectIt reports field coverage, duplicate note ids, unrecognised categories, notes with
no frontmatter, and bodies long enough to be truncated before embedding. Exit status is
0 clean, 1 warnings, 2 something is wrong.
3. Connect an AI client
Varven speaks the Model Context Protocol over Streamable HTTP, so any MCP client works. In Claude: Settings → Connectors → Add custom connector, then paste:
https://api.varven.net/mcpClaude will send you to a sign-in page. Approve, and the connector appears in your tool list. The same URL works in ChatGPT, Gemini, Cursor, and VS Code — see each client's own connector settings.
4. What your assistant can do
| Tool | What it does |
|---|---|
memory_search | Hybrid keyword and semantic search across your vault |
memory_get | Fetch one memory in full by id |
memory_briefing | Standing context: pinned items, preferences, corrections |
memory_timeline | What changed recently, in order |
All four are read-only in the current release. Writing from the cloud arrives with the Core plan.
Reading a result
Results carry flags worth paying attention to:
- stale — nobody has re-checked this claim inside its window. Events go stale in a month, notes in three, facts in six, decisions in a year. Preferences and corrections never do, because they are true by virtue of having been said.
- weak_match — even the best hit scored poorly. Probably not your answer, and your assistant should say so rather than writing confident prose around it.
- superseded — this was replaced by something newer. The old version stays queryable, which is what lets you ask when a thing changed instead of silently rewriting history.
When something looks wrong
Search returns nothing, but the vault has notes
Usually the first sync has not finished. Check the sync panel. If it says complete,
run --inspect — a vault with no recognised frontmatter syncs successfully
and searches badly.
The first question after a break is slow
The local model unloads when idle and takes about 30 seconds to reload into VRAM. That is not a hang. It only affects local operations; the cloud replica answers immediately.
The connector will not authorise
Almost always a URL mismatch. The address must be exactly
https://api.varven.net/mcp — no trailing slash, no http://.
OAuth resource identifiers are compared literally and a mismatch fails with an
unhelpful message.
Answers got worse and nothing errored
The local model is probably unreachable, and search has quietly degraded to keyword only. The status panel shows model health. This failure is silent by nature, which is why the indicator exists.