Using One Connect

One Ask and Dictionary

One Ask answers questions about your project from one committed revision, with exact citations. Dictionary is the index underneath, shared by you and every agent.

What it is#

Dictionary is the project's shared knowledge. It joins committed code, project docs, the design contract, team notes, an import graph, optional local semantic vectors and an optional Graphify code graph, all built from one exact Git revision. One Ask is how you query it, and agents query the same index through their tools. It supplies evidence with exact sources; it cannot guarantee an answer and never overrides a human decision.

• The One Ask dock on the canvas takes a quick question, shows cited sources, can summarize them with the bundled local model, and Add to canvas turns the answer into a One Ask node.
• The One Ask drawer (/docs, or Full view from the dock) adds intake status, the structure explorer, the agent packet preview, knowledge folders, local models and analytics.
• In the command palette, anything that matches no command becomes a One Ask question.

Intake#

Opening a project starts an intake job. Its stages:

1. Committed source. Resolve the integration branch to an exact commit (or HEAD if it does not exist yet), list the tree and read only the blobs not already cached. Intake never checks out, fetches, runs hooks, installs anything or runs a project command. Uncommitted and untracked work is never indexed.
2. Notes. One generated Markdown note per included file, plus Overview.md, in the project's own folder of the knowledge vault. After the first intake, only changed files' notes are rewritten.
3. Import graph. A declarative parse of symbols and file-to-file imports for TypeScript and JavaScript, Python, Rust, Go and Swift; doc-to-code path mentions; and manifests (npm, Cargo, pyproject and requirements, go.mod, Package.swift, Gemfile, Dockerfile, Compose). Nothing is executed. It is an import graph, not a call graph.
4. Keyword index. Local SQLite full-text search. Works without any model.
5. Semantic vectors (optional), from an embedding model already installed in a local Ollama on 127.0.0.1, or the bundled embedding model in the Mac app. Nothing is ever downloaded.
6. Graphify (optional). Your installed Graphify runs AST extraction only, on the same redacted snapshot, with LLM keys stripped.

Every stage records the revision it was built from. The overall state is Ready only when every stage matches the indexed revision and nothing was truncated; otherwise it is Partial, with the reason. A failed Graphify build keeps the previous graph, labelled Stale with its older revision.

Staying current#

• A cheap check runs every 30 seconds; an intake starts only when the integration revision moved. A failed intake is retried after 5 minutes.
• Each intake reports what was added, modified, deleted and renamed, and how many blobs were read or reused.
• Requests that arrive during an intake fold into one follow-up run. Cancel intake stops the job; the last published index keeps serving.
• An intake interrupted by a shutdown resumes on the next start.
• Queries never force a rebuild. They answer from the last published generation.

Limits#

Docs and manifests go first, then source, then tests and fixtures. Larger repositories are indexed partially and labelled PARTIAL everywhere. Symlinks, submodules, hidden folders (except .github and .gitlab), credential, env, key and certificate files, binaries, lockfiles, and generated and vendor trees such as node_modules, target and dist are excluded.

Asking#

Type a question and press ⌘↵. Retrieval:

1. fuses the keyword ranking with the semantic ranking when enabled;
2. promotes sources your question names by path, file name or symbol;
3. pulls in the imports and dependents of the strongest sources, marked related by imports;
4. removes near-duplicates, keeping at most two passages per source;
5. packs passages into a budget of 6,000 characters by default (knowledge.search.budget_chars).

Each citation names the exact file, revision, content hash and line range, and says how it was found: keyword, semantic or graph. View source opens the committed file at the cited lines. Excerpts are verbatim committed text, redacted.

Evidence verdict. Each answer is marked supported or insufficient evidence, based on how much of the question the cited excerpts cover; missing terms are listed. With an optional local answer model, One Ask also writes a plain-language answer labelled as an AI interpretation, in which every claim must cite a returned source. Retrieved text is always treated as data, never as instructions.

Knowledge folders and Obsidian#

Intake writes to a private Markdown vault by default. Choose your project knowledge connects an Obsidian vault or any Markdown folder instead:

• pick the vault, the folder for shared team notes (each project gets its own subfolder), and the readable folders, one per line;
• unlisted folders, hidden files and symlinks are excluded, and folder traversal is refused;
• the selection is a project setting, stored in that project's database.

The project's managed folder is named from a hash of the repository path, so two repositories with the same name stay isolated in a shared vault. Intake never overwrites or reads notes you added yourself, and repairs generated notes that were edited or deleted.

Semantic search#

Turn on Enable semantic search using local Ollama embeddings and name an already-installed embedding model (default embeddinggemma). The endpoint must be http://127.0.0.1 with no credentials. One Connect checks the model's embedding capability, never pulls a model and never calls a remote embedding service. If the model is unavailable, keyword search keeps working and the error is shown.

In the Mac app, the bundled embedding model is served on http://127.0.0.1:11435. Set the endpoint to that address and the model to qwen3-embedding:0.6b to use it.

Bundled local models#

The Mac app ships two small open models so summaries and semantic search work offline and free, without sending anything off your Mac.

Each model's SHA-256 is verified before first use. llama-server starts on demand on a random loopback port with a random key and stops after 10 quiet minutes. An Ollama-compatible bridge on 127.0.0.1:11435 refuses requests from browser origins and non-loopback hosts. If the files are missing or fail verification, the summary features say so; no other model is used.

What agents receive#

Agents use the same index through their tools: get_project_context, search_context, ask_project, read_note, and the Graphify tools query_graph, graph_path and explain_node. See Agent tools.

get_project_context returns one bounded packet (9,000 characters by default, 3,000 to 16,000) for the run's assignment:

• the indexed revision and every stage's freshness;
• how the run's base differs from it;
• the agent's own in-scope uncommitted work, labelled as not evidence;
• entry points, most-imported modules, packages and the design contract;
• other agents' status and declared ownership, never their transcripts, prompts or unfinished code;
• daemon-verified evidence and recent merges;
• cited retrieval for the issue.

What agents receive in the One Ask drawer previews exactly this packet for any issue.

Context benchmark#

acc bench context (also on the One Ask page) builds a disposable repository and vault, runs the real intake, and compares keyword-only, Dictionary, hybrid, Graphify and on-demand-skill retrieval with a full-context baseline on labelled questions. It reports bytes per question, an estimated token count (bytes ÷ 4), latency, retrieval accuracy, citation integrity and abstention, and fails on any regression. It calls no model and downloads nothing. Byte counts are not provider-reported tokens, and the benchmark is a regression guard, not an independent evaluation.

Analytics#

Query counts and the source characters supplied to answers appear in the drawer's analytics and in Insights → Analytics. These are retrieval measurements, not token savings.