gDown for AI

An AI assistant needs three things from a database: to understand its model, to find what it is looking for by meaning as well as by words, and to write without being able to break anything. gDown has all three built in, in the same engine and with the same rights as every other client.

MCP server

POST /mcp speaks the Model Context Protocol: Claude or any MCP client reads the schema (JSON, Mermaid, Cypher, JSON Schema, GraphQL), runs read queries, asks for a query plan without running it, and writes. It acts with the identity of its own token or account, so with its roles and privileges; a tool it may not use is not even listed. Saved queries (My APIs) are tools too.

Vector search

CREATE VECTOR INDEX on an embedding property, then db.index.vector.queryNodes returns the k nearest neighbours by cosine or Euclidean similarity. Exact search up to 2,000 vectors, then an approximate HNSW graph that follows updates.

Full-text search

CREATE FULLTEXT INDEX on several labels and properties, with analyzers (standard, simple, english, keyword...) and queries by terms, +required, -excluded, "exact phrase", prefix*, fuzzy~ and property:term, scored by tf-idf.

Both searches are queries like any other, so they combine with the graph in one statement: find the passages closest in meaning to a question, then follow the relationships to their source, author or product, and give the assistant that context. That is the basis of retrieval for AI answers (RAG) on connected data.

Writing without breaking anything

  • Dry run: a write runs in a transaction that is rolled back, and the agent sees the changes it would make.
  • Direct or staged: by default the write is applied at once, within the agent's rights; in staged mode it becomes a proposal, stored in a replicated database, that a reviewer promotes or rejects.
  • Rights of its own: give the agent a role limited to the databases and labels it needs, not the built-in writer role; it then cannot reach the proposals database.
  • Limits and trace: rows returned, statement size and writes per minute are capped; writes appear in the audit log (protocol mcp) and carry $_agent, $_at and $_source.

gDown AIM: memory for your AI assistant

gDown also remembers a project for Claude Code or any MCP client: push its Markdown files and commits, and the assistant asks the memory through the memory_* tools, within a token budget, with the source of every answer.

  • One bundle per repository: the Markdown files tracked by Git and the commits of the last days, pushed by a Python script without dependency (or by curl); gDown extracts typed facts (rules, decisions, pitfalls, plan items, properties, routes, limits) and replaces the previous state atomically.
  • Hybrid retrieval: concepts, full text and vectors; the embeddings are computed by gDown itself, in its own process (built-in model, default) or through your own Ollama or OpenAI-compatible API.
  • Five tools: memory_ask (a question, a repository, a budget), memory_context (what applies to a task), memory_about (a concept), memory_status and memory_note; every answer cites its source (file and line, commit or note).
  • A revocable API token bound to a local account limited to one database: the assistant reads and may only add notes (memory_note is its only write); DROP API TOKEN cuts its access at once.

Without embeddings (provider none, or an Ollama that does not answer) the push succeeds and retrieval is lexical until the backlog is embedded. Ollama (ollama pull bge-m3; on Linux it must listen on the Docker interface) is optional: the built-in model needs none.

Windows (PowerShell): start gDown as the memory, then create its database, roles and tokens (this machine only; Docker Desktop, no WSL2 or Git Bash needed)

Windows 10 or 11 with Docker Desktop, Git and Python 3 from python.org or the Microsoft Store (the launcher is py -3, or python if py is not installed); curl.exe and PowerShell come with Windows. -ExecutionPolicy Bypass applies to this one run and changes no setting. Connecting Claude Code is the same command as above, typed in PowerShell.

RAG: retrieval-augmented generation in gDown

gDown does retrieval-augmented generation (RAG): it finds the passages that answer a question, by meaning and by words, together with the graph around them, so that a language model answers from your data and cites it. gDown retrieves; the model that writes the answer is yours.

For assistants: gDown AIM

  • Ingestion: the Markdown files and the commits of a repository become typed facts and chunks of 1,000 characters with an overlap of 100.
  • Hybrid retrieval: the concept graph, full text and vectors (pre-filtered by repository) are combined, then ranked and cut to a token budget.
  • Every answer cites its source (file and line, commit or note).
  • Served through the MCP tools memory_ask, memory_context, memory_about and memory_note; the assistant's own model generates the answer.

For your applications

  • A vector index on any property: exact search up to 2,000 vectors, then an HNSW graph.
  • Pre-filtered search (labels, property values): the k results are counted after the filter.
  • Vector search, Cypher graph queries and full text are in the same database and the same statement: find the closest passages, then follow the relationships to their source.

Embeddings: built in or external

  • Built in (default, provider=onnx): the multilingual-e5-small model, quantised int8, 384 dimensions, runs in the gDown process through ONNX Runtime. The model files are pinned by SHA-256, downloaded once or read from a folder, and the model is unloaded when idle. No text leaves the server.
  • External (provider=http): Ollama (bge-m3 recommended, 1,024 dimensions) or an OpenAI-compatible API. The API token is sent only to that API and never logged, and the hosts the provider may call are restricted to an allow-list (loopback by default).
  • None (provider=none): retrieval uses the graph and full text only.
  • Changing the model: the chunks embedded by another model are marked stale and are re-embedded on demand.

Measured quality

gDown AIM was evaluated on three question sets against the real workspace (32 repositories). The table shows recall, the share of expected facts found, and the size of the answers: without vectors on the English corpus (2026-10-23, after the rework of the ranking), and with vectors (bge-m3 through Ollama) as measured on 2026-10-16. This table does not include the built-in ONNX model.

Question setWithout vectors (2026-10-23)With vectors (bge-m3, 2026-10-16)
1 (12 recorded questions)100.0 % · 22,103 tokens95.8 % · 22,517 tokens
2 (12 independent questions)100.0 % · 23,422 tokens100.0 % · 24,948 tokens
3 (9 ambiguous questions)94.4 % · 16,737 tokens88.9 % · 17,036 tokens

Recall and size of the answers in tokens. The two columns come from two runs, not one: the corpus and the ranking changed between them, so they are not comparable, and the vectors have not been measured again since the rework. On 2026-10-16 the vectors changed recall only on set 3 (+11.1 points) and made the answers shorter on sets 2 and 3.

Other measurements

Corpus evaluated

Read on 2026-10-16: 32 repositories and the assistant's memory folder, loaded in 32 seconds. The 2026-10-23 run follows the same method on the English corpus; its counts are not published.

ElementCount
Sections6,403
Plan items995
Properties568
Routes667
Features373
Decisions215
Limits66
End-to-end results57
Rules27
Pitfalls10
Commits (last 30 days)2,025
Measurements2,720
Concepts56

Embedding speed

Chunks embedded in one run. With the built-in model, queries wait while an ingestion embeds. No figure is published yet for processors with AVX2.

Provider and modelMachineChunksTime or speedQuery p50 / p90MemoryDate
Ollama, bge-m3 (external)A Mac9,954269 s––2026-10-16
Built-in ONNX, multilingual-e5-small int8Xeon E5-1620 v2, 4 cores, no AVX2, native build for x86-64-v2, 4 threads1,6901.6 → 2.0 chunks/s25.7 / 37 ms (server idle)2.4 GiB2026-10-22/23

Comparison with the pilot

The pilot ranking used the concept graph alone (2026-10-16). gDown now: without vectors, English corpus (2026-10-23). The minimums of the test are 95.8 / 100 / 83.3 %.

Question setPilot (2026-10-16)gDown now (2026-10-23)
1 (12 recorded questions)96 % · 20,291 tokens100.0 % · 22,103 tokens
2 (12 independent questions)100 % · 28,013 tokens100.0 % · 23,422 tokens
3 (9 ambiguous questions)83 % · 17,242 tokens94.4 % · 16,737 tokens

Memory size

Heap measured on 2026-10-17: with 384 MiB the server ran out of memory.

Memory databaseHeap neededDate
32 repositories, 3,298 code facts, 10,150 vectors1 GiB2026-10-17

Limits: the vector and full-text indexes live in memory and are rebuilt when the database opens; no server-to-client stream, no OAuth specific to MCP (token or account, like the other routes); memory: without embeddings (provider none, or an Ollama that does not answer) retrieval is lexical until the backlog is embedded. No benchmark of vector search or of MCP is published yet: the figures on this page do not cover them.