Knowledge graph

The knowledge graph is nima's memory of your product: the features, decisions, requirements, customers and people it has learned about, with the source of every fact. Specs, the Slack assistant and coding agents all read from it.

What the knowledge graph stores

The knowledge graph stores entities, the relations between them, and facts about each entity. Each workspace has its own graph, and a question only ever searches the graph of the workspace the caller belongs to.

• 12 entity types: feature, user_need, technical_decision, constraint, requirement, discovered_concept, person, customer, product, goal, signal, organization.
• 17 relation types: implements, depends_on, requested, owns, part_of, prioritized_by, signals, contacted_about, decided_by, constrained_by, specified_by, contradicts, supersedes, relates_to, blocks, enables, serves.
• Facts are key and value pairs on an entity. Every fact records its source, the date nima learned it, and a confidence between 0.1 and 1.0.

A fact can be marked confirmed or assumed, or carry no mark. nima marks a fact as assumed when the source hedged ("proposed", "tentative", "TBD", "we think"), and the answer shows ASSUMED next to it so nobody reads a guess as a decision. It marks a fact confirmed only when the source stated it as settled. Most facts carry neither mark, which means the source did not say either way, not that the fact is confirmed. Confidence starts from the source (a spec is 0.95, a merged pull request 0.85, a Slack message 0.7) and moves up or down as other sources agree or disagree. Newer facts count for more: the recency weight halves every 90 days.

The same thing is often described differently in a spec, a PR title and a Slack thread. nima resolves names and aliases to one entity when it is confident they match, and can still leave two entities for one thing (see Knowledge graph limits).

Knowledge graph sources

Every fact carries one of 13 source labels, so you can tell a spec from a Slack remark.

Signals from connected tools reach the graph through extraction of the signal itself, so a tool feeds the graph only as far as it feeds signals. Jira is not a graph source.

When a fact comes from a signal, the answer tags its origin as [customer], [external], [internal] or [internal channel]. A signal from a Slack channel nobody classified is [internal channel]: it says where the message was posted, not who wrote it. Do not read every SIGNAL source as a customer.

Contradictions and superseded knowledge

The knowledge graph keeps conflicting values and flags them; it does not silently pick one. When two sources give different values for the same fact key on an entity, the answer shows both values, each with its source and the date the conflict was detected, up to five per entity (line format on Knowledge API). A reworded value is a wording change, not a conflict. Conflicts are only detected between facts that share a key, so a flag can be a false positive (for example "active" against "existing").

Knowledge that has been replaced is marked, not deleted. When nima can prove that a newer entity describes the same subject as an older one, it links them with a supersedes relation. The older entity is ranked below current ones and its answer opens with a Superseded by warning naming the newer entity, which says the facts below describe how this used to work. In agent mode the same information is the supersededBy field.

When a conflict is resolved, the losing source's other facts and relations are discounted (confidence times 0.8); unresolved conflicts stay flagged. Every graph write is journalled and can be undone for 30 days by a workspace owner or admin over a signed-in session, or ask the nima team. The journal is not reachable with an API key.

Modality: implemented, fixed, proposal, problem

Every entity in an answer carries one word, its modality, that says whether the graph has evidence the thing exists in your product. The word appears in square brackets after the entity type.

An entity with no facts has no modality, and the label is left out.

Pull requests that never shipped

A pull request entity that did not merge is banner-marked, so nothing it describes is read as applied. A closed pull request shows NOT SHIPPED: this pull request was closed without merging. An open one shows NOT SHIPPED YET: this pull request is still open. Relations asserted by such a pull request carry the same flag on the line. A merged pull request shows no banner.

Only merged pull requests feed the graph with facts. The PR state is refreshed on every GitHub webhook, so a pull request that merges later loses its banner. The delivery page covers how nima tracks a spec to its merge.

Ask the knowledge graph a question

There are three ways to ask the knowledge graph a question, and all three search the same graph.

• MCP: the ask_knowledge_graph tool, documented on Knowledge tools.
• REST: GET /v1/knowledge-graph/ask, documented on Knowledge API. Parameters are q (2 to 500 characters), limit (1 to 20, default 8) and mode.
• Slack: mention nima or message it. The assistant queries the graph and answers in prose. See Slack.

By default the answer is markdown: matching entities with a summary, up to 5 facts, up to 5 relations and any conflicts. Pass mode=agent to get compact JSON instead, meant for programs. It has no prose and no cap on facts and relations, and it carries fields such as modality, match, supersededBy and conflicts.

If your question names something literal, such as a file path, a symbol, a constant, a ticket key like BCN-23, a pull request number or anything in quotes, nima returns every entity that carries it first and flags each one (exact) or, for a fact match, (exact: fact <key>). When nothing in the graph is the thing you named, the answer opens with a warning and marks results (no exact match): they are semantic neighbours, not the thing you asked about. A fabricated name comes back looking like a real one unless you read the flag.

Questions in a non-Latin script (Hebrew, Arabic, Russian, Chinese) are translated to English before searching. The answer opens with a line saying what was searched, and its content stays in English. English questions are never translated.

The graph says why and who. For where something is in the code, use search_code and the other tools described on Code intelligence.

Knowledge graph limits

The knowledge graph is retrieval, not a chat model or a database you can browse, and a few limits follow from that.

• Similarity floor. An entity must reach a similarity of 0.6 with your question to be returned by meaning. Entities matched by name, alias or an exact identifier skip the floor. When the meaning search finds nothing, a literal text fallback can still return entities, and those show Similarity: 0.000, which means found by text, with no similarity score.
• Nothing found is not proof of absence. The graph holds only what your connected tools told nima. "No entities found" means the graph has nothing on the subject, not that nothing exists.
• English only. Non-Latin questions are translated; Latin-script questions in other languages are not.
• Top 5. Each entity shows at most 5 facts and 5 relations in markdown, with a line saying how many were omitted. Facts that carry a literal you named come first.
• One thing, several entities. A feature and a discovered concept, or two decisions learned in separate passes, can describe one thing. Read the neighbours before concluding.
• Summaries can be stale. A summary marked Summary is stale since <date> should be checked against the facts under it. The facts and excerpts are the evidence.
• No editing or browsing. No API route or MCP tool lets you list, edit, correct or delete entities and facts. The graph visualization, the change journal and undo are not reachable with an API key and have no page in the admin panel. If a fact is wrong, ask the nima team.
• Rate. GET /v1/knowledge-graph/ask allows 300 requests per 10 seconds. Over MCP every call also passes through the MCP endpoint, which allows 100 per minute, so an agent that fans out many questions in parallel hits that limit first. See Rate limits.