The Curltale AI guide

Overview

Two halves, one bridge

Curltale AI keeps two kinds of knowledge apart because they are governed differently, and connects them because agents need both.

Nothing from a document ever enters the ontology. A topic can point at an entity, and that pointer is stored inside the collection that holds the document. If you cannot read the collection, you never see the link, and nothing in the model is left dangling.

Overview

The knowledge model

The ontology answers "what does this data mean and how do I query it". The knowledge base answers "what do we know, and where does it say so". Both are indexed for search; neither is copied into the other.

Overview

Retrieval

Sixteen read-only tools: six for the data and ten for the documents. On the document side, chunks are how the system finds and whole pages are what it returns. Search everywhere combines meaning (vectors) and words (full text) by reciprocal rank, so exact codes and paraphrases are both found.

Only what is served is searched: the approved version of a source wiki and the published version of an active topic. A held change is invisible to agents until a person approves it. Every result names its collection and carries its usage tag.

Ontology

What the model holds

Only the structured meaning of your data. Everything an agent or a person needs to build a correct query is one of these.

SQL in the model is written once in PostgreSQL syntax and translated for whichever database is connected.

Ontology

Draft, review, publish

The model is versioned like code. Agents only ever see the published version.

1. Start a draft. A copy of the published version, or a new one from a spreadsheet or a connector.
2. Edit. In the app, by uploading Excel, or by generating from a database. Every change is written to the audit log with who and when.
3. Validate. References resolve, required properties exist, values come from allowed lists, restricted fields have no agent access. SQL that does not run on the connected database is advice, never a blocker.
4. Review. Compare the draft with the published version, item by item.
5. Publish. The search index is built and embedded in the background, and only then does the draft become the published version. If it fails, the draft stays a draft.

An optional four-eyes rule means whoever changed a draft cannot publish it. After a publish, the instructions agents receive are rebuilt and every tool reads the new version.

Ontology

Start from a file or a database

Everything generated is marked needs review. It is a starting point to which your team adds meaning, filters and calculated fields.

Ontology

Search and model check

No data yet? Build a demo database generated from your published model, with keys, links and allowed values respected, to try everything before connecting the real one.

Knowledge

Collections

A collection is the unit of isolation. Its documents, passages, topics, statements, links, vocabulary and jobs belong to it alone, and nothing is ever combined across collections.

Knowledge

Add documents

Places are kept so passages can be cited: page 3, slide 2, sheet "Costs". Web pages lose their menus, footers and cookie banners, and spreadsheets are read row by row with their column names.

Knowledge

From document to topic

Each source goes through the same pipeline. Models see only the one document of the job, with tools filtered to its collection.

1. Read and splitText is extracted with its places (page, slide, sheet), cut into passages, embedded and indexed. No AI model needed.
2. Write the source wikiA writer model drafts a standalone page that keeps every fact, number and exception. Every version is chunked and embedded.
3. Verify itA second model verifies the page claim by claim against the document. A failure that names no problem is re-checked, never amended blindly.
4. CorrectReal problems go back to the writer with the evidence, up to a set number of rounds.
5. Approve or holdA page that passes is approved. One that still has objections waits for a person.
6. Build topicsAn analyzer finds the subjects and extracts atomic claims, each with a quote that must appear word for word in the wiki. The topic writer writes each page from the full verified wiki and can read other sources' wikis.
7. Link to the modelTopics are linked to the entities they are about, with a confidence. Doubtful links wait.

A different model can do each job (writer, checker, analyzer, topic writer, interviewer, image reader), or one model can do all of them. If the topic writer fails, a plain page is built from the candidate so nothing is lost. A claim found again in another source attaches to the existing one, so numbers stay stable. A topic a source no longer mentions gets a surgical rewrite that removes only what no remaining source supports.

Knowledge

Review

Most updates publish at once. What is doubtful waits in the collection's queue, and agents see nothing of it until a person decides.

The queue belongs to the collection, not to a person, so whoever is free picks it up. Readers do not see it, because held changes are unpublished. Two held changes on one topic never build on each other's unapproved work.

Knowledge

Topics and evidence

A topic is a page by subject, not by document. Two documents about the same product end up on one page.

Knowledge

The bridge to the model

A topic can say what it is about. The Pro plan is a kind of Product. The refund policy governs Invoice.

• Made while reading. The analyzer is shown the model's entities (name, domain, a short definition, never data) and says which ones each topic is about, with a relation and a confidence. At 70% or more the link is confirmed at once, and less waits as a suggestion.
• Stored in the collection. The model gets no new entity and no new relationship. Whoever cannot read the collection sees no link and nothing broken.
• Visible both ways. On the topic page, on the entity page as related documents, over the model graph, and for agents through the tools.
• Resolved when read, with the reader's own entitlements. A link to a field never exposes personal, confidential or restricted ones.

Knowledge

Interviews

Some of the most useful knowledge has never been written down. The interviewer captures it the way a curious colleague would.

1. Say what you want to document in your own words.
2. Answer questions one at a time. The interviewer reflects back, follows threads, asks for specifics and checks stored facts against what you say next.
3. Review the facts it extracted after every exchange (trigger, step, decision, exception). Correct or remove any of them.
4. Write the draft. Every fact appears, nothing else is added. Edit it and save new versions.
5. Add it to the collection as a source that becomes topics like any document. A person already reviewed it, so the writer and checker are skipped.

Knowledge

Keeping it healthy

A collection exports as one zip: the original files, every source page with its versions and checks, each topic as Markdown with its statements and evidence as JSON, the links, the vocabulary and a manifest. It is a handover format, and nothing from any other collection can be in it.

Agents

The MCP server

One endpoint for any MCP client that speaks streamable HTTP with a bearer token. Ten read-only tools, and the server explains itself, so there is nothing to prompt-engineer.

claude mcp add --transport http curltale https://<your-host>/mcp \
  --header "Authorization: Bearer <token>"

The ten library_ tools only appear to a token that holds a grant on at least one collection. A token without grants sees six tools and no trace of the library.

Agents

Alfred

The built-in assistant. It uses the same tools and the same rules as an external agent, under the signed-in person's own access.

• It knows which page you are on, so "what does this field mean?" works on a field page.
• It decides when it needs the documents. A data question uses the model and the data, a policy question searches the library, and a general question needs no tool.
• It streams its answer, shows every tool it calls, and links the entities, fields, topics and documents it used.
• It starts every document question with library_context, which returns whole topic pages, and goes to claims, related topics or the verified source wikis only for a detail a page lacks. If the documents do not cover a question, it says so.
• Instructions found inside data or documents are treated as content, never as commands, and internal collections are never quoted in customer-facing text.
• It runs on any OpenAI-compatible endpoint. Without one, Alfred is off and everything else keeps working.

Governance

Protecting data

Governance

Protecting documents

1. GrantsA collection is reachable only through a grant. Without one the answer is the same as for a collection that does not exist.
2. Agent switchA collection can keep every agent away, whatever the grants say.
3. AI switchA collection can keep every model away. It stays stored and searchable locally.
4. Isolation in the databaseComposite keys make the database itself refuse a passage that names a source from another collection.
5. Usage tagEvery result says whether it may be shared with customers.
6. AuditGrants, self-grants, uploads, removals and exports are logged, by id, never by file name.

Governance

People and roles

Passwords are stored with scrypt and need at least 12 characters. Sign-in locks after repeated failures, a password set by an admin is temporary, and changing your password ends your other sessions. Every assistant conversation and agent session is recorded step by step, with tokens, cost, timing and the response returned.

Run it

Install

Docker with Compose v2 and about 2 GB of memory. Two containers to start: the app and PostgreSQL with pgvector.

git clone https://github.com/curltale/curltale.git && cd curltale
cp docker-compose.example.yml docker-compose.yml
cp .env.example .env          # fill in the required values
docker compose up -d          # open http://localhost:8080

1. Sign in with the first administrator from your .env.
2. Add an AI endpoint (optional, but Alfred and most of the library use it) and press Test.
3. Start the ontology from a spreadsheet or a connector, review, publish.
4. Try it: build the demo database, ask Alfred, or create a token and connect an agent.
5. Add knowledge: create a collection, give people the editor role and a grant, and upload documents.

Run it

Optional services

Everything beyond the core is an overlay file you add with -f. They combine freely.

docker compose -f docker-compose.yml \
  -f docker-compose.worker.yml -f docker-compose.fetcher.yml -f docker-compose.storage.yml \
  up -d --build

Choose the storage before the first upload. Files already stored are not moved when the driver changes.

Run it

Models and settings

Behind a proxy, the app reads the real client address from a forwarded header only when the request comes from a trusted proxy. It also sets its own security headers and rate limits, so it is safe with no proxy in front.

Run it

Operations

• Update: rebuild and restart with the same -f files. Schema changes apply at startup and missing embeddings fill in the background.
• Back up three places: the database, the library's original files (data folder or bucket), and the rest of the data folder with Excel backups and connector files.
• Rotate a token: create the new one, update the agent, revoke the old.
• Observe: an activity log of every conversation, tool call and model call with cost, summaries per tool and per model, and a health endpoint for monitors.
• Audit: a vulnerability scan script checks the locked Python packages and the interface's runtime packages.

Under the hood

Architecture

One PostgreSQL database with pgvector holds the model, its versions, the library, the search indexes and the app's own data. No separate graph or vector store is needed at this scale.

• Deterministic where it matters. The query planner and the join-path finder are plain code. SQL is parsed and generated with sqlglot, with one driver class per database kind.
• The library has its own schema in the same database, with composite keys that enforce isolation, and a job queue with leases and retries.
• The interface is React, served by the app. Model-written text is rendered without HTML or images.
• Tested. Hundreds of tests run on a fictional model of a subscription business, including route sweeps that prove every endpoint checks access.

Under the hood

Limits

What it does not do yet, stated plainly.

• One model per installation, and one active connector at a time.
• Access to data is decided per column. Row-level rules are not implemented.
• Agents receive a capped number of rows per query and results are not paged, so they are told to aggregate or filter.
• Sign-in is username and password. Single sign-on and multi-factor authentication are not built in yet.
• Rate limits are kept in memory, which suits one app process.
• A collection export has no matching import yet, and the browser service does not read pages behind a login.