Knowledge graph

Carabase keeps two complementary views over the same workspace content, so the agent can answer questions like “what did Alice ship for the fundraise project last quarter?” without you manually linking anything.

• The typed graph (entities + edges) is fact-shaped — subject / predicate / object relationships, each carrying explicit trust provenance.
• The memory network (associative notes linked Zettelkasten-style) captures softer, evolving context and is walkable as its own graph.

Both are isolated per workspace, built incrementally from your daily notes and connector data, and reachable through the MCP retrieval tools.

Entities

Every person, project, organization, tool, concept, topic, or event you mention becomes a row in the entities table. Each entity has a name, a type (person, project, organization, tool, concept, topic, event), and a flag indicating whether it is the canonical record or an alias pointing at one.

Concept roots

Two entities per workspace get a special role via the first-class concept_role column:

• me — the person the workspace is about.
• primary_org — their primary organization.

These roots are surfaced in agent context to anchor pronoun resolution and “we” references. Curation can also tag historical organizations (a former employer) so the graph remembers them without treating them as current.

Aliases

People and things go by multiple names. A non-canonical entity points at its canonical record, so “Alice”, “Alice Chen”, and “A. Chen” all resolve to one node. The corpus curator proposes alias merges; you accept or reject them in the curation queue. Trivial, banal variants (legal suffixes, plurals, casing) auto-merge without a prompt — human review is reserved for genuine ambiguity.

Code-identifier gate

Ingested source code used to leak class and function names (like PanoptoBaseIE) into the graph as bogus entities. A deterministic, narrowly-scoped check drops obvious code identifiers — CamelCase-with-acronym, snake_case, dotted module paths, call syntax, source-file names — before they become entities, while leaving legitimate names (OpenAI, PostgreSQL, iPhone, Node.js) untouched.

Edges

Relationships between entities are rows in the edges table. Beyond the two endpoints and a relationship type (works_at, manages, founded, …), every edge carries three provenance fields that let downstream consumers ask trust-aware questions:

Field	Meaning
source_kind	How the relation was obtained: extracted (direct observation), inferred (derived), or ambiguous.
confidence	A [0, 1] score for how much to trust the relation.
provenance	A record of the originating fact, account, and source.

Every edge producer sets source_kind and confidence explicitly. Leaving them to default would silently promote junk into high-trust territory, so a CI guard enforces that they are always supplied.

The trust value is resolved at a single policy seam. Most typed relations pass through unchanged, but vacuous co-occurrence relations are capped because they assert almost nothing:

Relation	Cap	Why
related_to	≤ 0.40	pure co-occurrence, no asserted semantics
mentioned_in	≤ 0.50	a direct mention — slightly more signal

The cap clamps confidence only; source_kind stays honest (the observation is real, the relation is weak). carabase_search_graph applies no default floor — the agent sees honest scores and opts into min_confidence / source_kinds filters when it wants only high-trust facts.

How the graph gets built

1. Daily notes accumulate logCards — from your typing, from connectors, and from agentic flows.
2. The harvest pipeline reads each logCard and extracts entities and relationships. Direct observations are stamped extracted with full confidence (then capped for vacuous relation types).
3. Entities are upserted with alias resolution; edges are inserted with their provenance.
4. The memory-graph bridge translates distilled facts into edges, stamped inferred with lower confidence — a two-hop derivation can never outrank a first-hand observation.
5. Nightly, the corpus curator walks the graph and suggests alias merges, role enrichment, and cleanup — all as curation suggestions for you to accept or reject.

Memory network

Alongside the typed graph, Carabase maintains an associative memory network — A-MEM-style notes, each carrying LLM-authored keywords, tags, and a contextual description, linked to neighbouring notes and to the source artifacts that support them.

Memories come from three sources: explicit facts distilled from a chat turn, a nightly distillation pass, and bulk import / backfill. Each new memory runs through a resumable three-stage pipeline:

1. Note construction — author its keywords, tags, and contextual description.
2. Embedding — embed the fact together with that description for semantic recall.
3. Link generation — find the nearest existing notes and let an LLM judge which to link, by what relationship, and with what confidence.

Links use a closed set of relationship types — some directed (causally_precedes, elaborates, contradicts, supersedes) and some symmetric (references_same_entity, temporally_co_occurs, topical_neighbour). The agent walks this network with carabase_traverse_memory_network, starting from one or more anchor memories. The pipeline is on by default and bounded by a daily token budget.

Bi-temporal edge validity (opt-in)

Facts change — people switch jobs, move cities, change roles. Carabase has built-in support for bi-temporal edge validity: edges can record when a fact was true separately from when it was recorded, and contradictions are resolved by invalidating, never deleting — so a superseded fact survives for time-travel and audit.

This is default-OFF, gated behind a per-workspace setting. At rest the supporting columns are written but never read, so the graph behaves exactly as before. When an operator turns it on:

• A new edge for a single-valued relation (one where a subject has exactly one current target — works_at, lives_in, married_to, reports_to, current_role, …) pointing at a different target than the existing valid one is treated as an unambiguous supersession and resolved deterministically, no LLM required.
• Other relationships are handed to a contradiction-detection skill that only invalidates on an explicit conflict. Multi-valued relations (knows, advises, member_of) and vacuous co-occurrence relations are excluded — a second edge there is not a contradiction.
• Only the high-trust extracted harvester path can trigger invalidation; inferred bridge edges can never retire a first-hand fact.
• carabase_search_graph then returns currently-valid edges by default and supports as_of time-travel.

How the agent queries it

The graph and memory network are reachable through the MCP retrieval tools shipped in @carabase/mcp-server (14 canonical tools today). The graph-and-memory-relevant ones include:

• carabase_search_semantic — pgvector semantic search across artifacts.
• carabase_search_graph — graph traversal from a named entity, with optional min_confidence / source_kinds filters (and, when bi-temporal validity is on, an as_of cutoff).
• carabase_query_metadata — structured queries by entity name, folio, or date.
• carabase_find_entity_candidates — disambiguation lookup.
• carabase_traverse_memory_network — walk the associative memory links from anchor memories.
• carabase_verify_hypothesis — corroborate or contradict a claim against retrieved evidence.
• carabase_route_and_execute — pick the right strategy based on the shape of the query.

Each result carries provenance and confidence, so the agent can phrase its answer with appropriate hedging.

Hypothesis verification

Before committing to an answer of the form “did X happen?”, the agent can call carabase_verify_hypothesis. It runs a semantic search for relevant passages, then judges each one as supporting, refuting, or neutral with respect to the claim — using an LLM entailment judge — and returns a verdict (corroborated, contradicted, mixed, or inconclusive) along with the supporting and contradicting evidence. If no LLM judge is available it falls back to a lightweight lexical-overlap-and-negation heuristic. Either way, the agent can correct itself instead of confidently stating something the corpus disagrees with.