Knowledge Graph

The store is a SQLite database at ~/.flowly/knowledge_graph.sqlite3 (created lazily on first use). It is the structured counterpart to MEMORY.md: the agent is directed to record structured facts here rather than appending prose to memory.

Data model

The graph holds three kinds of records:

Entities

Nodes in the graph — people, companies, projects, events, or unknown.

• Each entity has a normalized id derived from its name (lowercased, trimmed, spaces become underscores, apostrophes stripped). For example "O'Brien Corp" → obrien_corp.
• Entity type is one of person | company | project | event | unknown. An entity's type is upgraded from unknown to a concrete type when better information arrives, but is never downgraded.
• Entities carry an optional JSON properties bag.

Triples (facts)

Directed subject — predicate — object statements, each with a validity window:

• valid_from / valid_to are ISO date strings.
• A fact is current iff valid_to IS NULL. Setting valid_to marks the fact as ended (historical).
• Triples also carry confidence (default 1.0) and source (default agent).

Entity vs value predicates. For most predicates, the object is another entity id. But a fixed set of value predicates store the object as plain normalized text instead of creating an entity node:

email, phone, url, website, address, location,
birthday, age, role, title, salary, note

So alice — email — alice@example.com stores the email as text, not as an entity.

Aliases

Alternate names mapping to a canonical entity id, used during name resolution.

Name resolution

When a lookup misses, the tool may surface "Did you mean…?" suggestions (partial LIKE matches), but it never auto-resolves to them; you must use the exact name or register an alias.

The knowledge_graph tool

A single action-dispatched tool. It requires no approval — same trust level as memory_append.

Actions

Parameters

Examples

Add a fact:

{
  "action": "add",
  "subject": "Alice",
  "subject_type": "person",
  "predicate": "works_at",
  "object": "Nocetic",
  "object_type": "company"
}

Store a value predicate (object kept as plain text):

{
  "action": "add",
  "subject": "Alice",
  "predicate": "email",
  "object": "alice@example.com"
}

Query an entity's current relationships:

{ "action": "query", "name": "Alice", "direction": "both" }

Query as of a past date:

{ "action": "query", "name": "Alice", "as_of": "2025-01-01" }

Invalidate a fact that is no longer true:

{
  "action": "invalidate",
  "subject": "Alice",
  "predicate": "works_at",
  "object": "Nocetic",
  "ended": "2026-03-01"
}

Merge a duplicate entity into a canonical one (source → target):

{ "action": "merge", "subject": "Alice B.", "object": "Alice" }

merge moves all of the source's triples to the target, registers the source name as an alias of the target, and de-duplicates the result.

Tool-side guards

• Comma-separated subjects are rejected.
• Comma-separated objects are rejected unless the predicate is one of email, phone, address, note, url.
• On a name miss, the tool returns "Did you mean…?" suggestions rather than guessing.

How the KG enters the system prompt

A compact KG summary (top entities by current-fact count) is injected into the main agent's system prompt as a # Knowledge Graph section. Subagents receive a ## Known Facts summary the same way — and that subagent path additionally scans the summary for prompt-injection payloads before injecting it.

Notes / limitations

• Value predicates are plain text. Objects for the value predicates listed above are stored as normalized text, not entity nodes, so they won't appear as graph entities.

Related

• Memory
• Delegation
• Features overview
• Sessions
• Tools reference