▸How-to Everyone
Need to hook Python into a local graph database
Connect to a local Neo4j database from Python using the Bolt protocol
Track 15 · Advanced
15.3
Temporal knowledge graphs
What did I believe in March, and what do I believe now?
1Overview
A graph of entities and relationships, each edge stamped with when it became true and when it stopped, built automatically from documents and conversations.
A vector store can tell you what is similar. It cannot tell you that a fact replaced another fact, or when. → This chapter builds memory as entities and relationships with validity intervals, so the system can answer questions about change rather than only about content — which is what "remembering" actually means for a person or an organisation. → It also builds the personal knowledge graph version, over plain markdown files you own, which turns out to be the one most people keep using.
Memory with time in it. Entities and edges carrying validity intervals, so a superseded fact is superseded rather than merely outnumbered — and a system that can answer "what changed since March" instead of only "what is similar to this".
1.1Before you start
1.2After this chapter you can
→Explain the difference between a vector store and a knowledge graph as memory
→Model entities, relationships and validity intervals over your own notes
→Answer a question about what changed, not just what is stored
→Ingest a conversation into a graph without hand-labelling it
→Build a personal knowledge graph over markdown files you control
→Judge when a graph is worth its complexity and when a vector store is enough
1.3When to reach for it
When facts change and the change matters: people, projects, decisions, prices, org charts — anything where the old value is not simply wrong but historical.
1.4Key parts
An entity extractor, an edge store with bi-temporal validity, a resolution step for duplicates, and a query layer that understands "as of".
1.5Free vs paid
The frameworks are open source; the graph database underneath may not be. The markdown-file variant costs nothing at all.
1.6Watch out
Graph extraction is an LLM job and it makes mistakes with confidence. A graph nobody inspects accumulates plausible edges that were never true.
2Lessons 7
2.1 Distinguish current facts from similar past facts
A bi‑temporal knowledge graph stores each edge with a validity window (when the fact was true) and provenance timestamps, letting it distinguish current facts from outdated ones, unlike a plain vector store that only ranks by similarity.
Separate similarity retrieval from change tracking and see why a vector store cannot represent “this fact replaced that one”
- Query the vector store with a question such as "who owns the Atlas project"
- Observe that the returned passages include both current and outdated information, ranked only by wording overlap
- Query a bi‑temporal knowledge graph with the same question and request the current answer
- You'll see The vector store returns multiple similar passages, while the temporal graph shows only the current owner (and optionally a history list)
- Takeaway A vector store finds what's similar; a bi‑temporal graph is needed to know what’s currently true because each edge carries start and end times
- Check Why does a vector store return both current and outdated owners when you ask “who owns the Atlas project”, whereas a bi‑temporal graph can give only the current owner?
- Cost Free to reason about — this lesson is conceptual.
2.2 Build a simple knowledge graph by writing markdown notes
Markdown files with frontmatter, bracketed‑category observation lines and verb‑prefixed wikilink relations encode entities for the graph tool.
Produce three markdown files that define entities, observations and relations readable by the graph tool
- Open a text editor and create a new markdown file for the first entity
- Add frontmatter with title, permalink and tags to name the entity
- Write an observation line starting with "- [category]" that records a fact about the entity
- Insert a relation line using "- verb [[Target Note]]" to link this entity to another
- Save the file in your notes folder, then repeat the process for two more entities, ensuring each has at least one observation and that one relation connects two of them
- You'll see Three markdown files containing frontmatter, bracketed‑category observation lines and a wikilink relation, which the MCP tool returns as connected graph edges
- Takeaway The whole graph is encoded in plain markdown files using bracketed observations and verb‑prefixed wikilinks
- Check What elements must each markdown file contain so that the MCP tool recognises it as an entity in the knowledge graph?
- Cost Free — a text editor and the notes you already have.
2.3 Query past beliefs using validity intervals
Validity intervals are four timestamps on each edge – valid‑from, valid‑to, observed‑at and ingested‑at – that define when a fact is true and where it came from, enabling point‑in‑time queries.
Answer what was believed in March and what replaced it by applying validity intervals
- Add a fourth observation that contradicts an earlier fact in the graph
- Assign a start timestamp to the new observation and set an end timestamp on the superseded edge using the four‑timestamp model
- Query the graph for edges whose valid‑from/valid‑to window contains March 1st to see the belief at that time
- You'll see An edge "Marta owns Atlas" shows a valid‑from date, a valid‑to date after correction, and a new edge with its own start timestamp, all displayed in the graph view
- Takeaway Validity intervals let you keep old facts for historic queries while still answering current truth
- Check How do start and end timestamps on edges enable you to retrieve the belief that was valid on March 1st?
- Cost Conceptual — no build yet. The database and query engine arrive in lesson 5.
2.4 Import raw text and inspect automatic extraction
The cognify extractor creates EntityNode and EntityEdge objects linked to the newly added episode, recording provenance for each fact.
Insert a paragraph into the system and view the entities and relations it generates
- Click add and paste your paragraph to create an episode
- Press cognify to run the extractor, which creates EntityNode and EntityEdge objects linked to that episode
- Open the graph view, expand the entities and edges, and compare each fact with the original sentence
- You'll see The paragraph appears as an episode and a list of entity‑edge pairs is displayed, with most items correct and at least one debatable relation
- Takeaway Automatic extraction saves you from hand‑crafting a schema but still requires a human check on every generated edge
- Check What objects does the cognify extractor create from a pasted paragraph, and how are they linked to the episode?
- Cost An LLM call per episode (extraction) plus the graph database's own resource cost. Both anchors are open source; the model doing the extraction is the metered part.
2.5 Make markdown files work as a traversable personal knowledge graph
The build_context command traverses wikilinks across markdown notes to assemble a combined answer.
Create a knowledge graph from your notes that an assistant can query without installing a separate database
- Install basic-memory using your package manager
- Configure basic-memory to point at the folder containing your markdown notes
- Start the MCP server that hosts the assistant interface
- Query the assistant with the build_context command to traverse wikilinks and assemble related notes
- You'll see The assistant answers “what do I know about the Atlas project” by returning content from three linked markdown files stitched together
- Takeaway A markdown‑plus‑wikilink knowledge graph with an MCP server is the simplest personal setup with the fewest moving parts
- Check Which command lets the assistant traverse wikilinks across your markdown notes to assemble related information after configuring basic‑memory?
- Cost Free — an MCP server process and the notes you already own. No hosted tier is required for this mode.
2.6 Decide if your project needs a graph
A checklist of three conditions—merged identity across documents, historic value relevance, and change‑focused queries—guides the decision to use a graph.
Choose whether to use a graph database for a specific project using a short checklist
- List the three conditions that justify a graph: merged identity across documents, facts whose old value still matters, and questions about change
- Check your project against each condition and note which ones apply
- If none apply, record “not‑yet” and plan to start with your existing vector store
- If one or more apply, record “graph” and consider a graph database for the next phase
- You'll see You will have written down either “graph” or “not‑yet” for the project you named
- Takeaway Only use a graph when you need merged identities, historic values, or change‑focused queries
- Check What three project characteristics indicate that adopting a graph database would be advantageous?
- Cost Free. The cost this lesson is trying to help you avoid is the one that shows up later, in maintenance.
2.7 Inspect edges to keep your graph trustworthy
Edge verification involves opening an edge’s source episode and checking whether the statement was directly quoted or inferred, determining its trustworthiness.
Prevent unverified edges from contaminating future queries by spot‑checking after each ingestion batch
- Open the graph view that lists recent ingestion batches
- Select an edge from a batch and open its linked source episode
- Compare the episode text with the edge wording and mark the edge as verified or unverified
- You'll see When you open an edge’s source episode you can tell whether the statement was quoted directly or inferred by the model
- Takeaway A knowledge graph remains reliable only while humans regularly verify its edges
- Check How does comparing an edge’s wording with its source episode help you decide whether the edge should be marked verified?
- Cost The spot-check habit costs a few minutes per ingestion batch. Skipping it costs nothing today and an unknown amount of wrong context, later, at a time you won't be looking for it.
3You’ll know it worked 8 checkable outcomes in this chapter
- ✓Run a Cypher query that returns facts valid at a given date and see that outdated facts are excluded
- ✓Ask the graph: MATCH (n) WHERE n.title='My Belief' AND n.sysStart <= date('2023-03-01') RETURN n.value and compare to a query for today’s sysStart.
- ✓After ingesting contradictory data, query the graph for active edges (WHERE r.validTo IS NULL OR r.validTo > now()) and confirm the old edge is excluded.
- ✓Run a Cypher query for a known entity and see that the returned relationship includes a 'valid_from' and 'valid_to' property
- ✓Ask the agent “Where did Alice work in 2019?” and receive only the relationship whose interval covers 2019
- ✓After adding "Dr. Chen left Stanford in 2020", query “Where does Dr. Chen work now?” and see only the new relationship; querying 2019 still shows Stanford.
- ✓Run a query for an entity at two different dates and see distinct relationship sets
- ✓The query results differ when you change the time filter, showing earlier vs. current beliefs
4FAQ, Tips & How-to 10
one problem, one solution, one action
▸How-to Everyone
Separate person, channel and OS records
Build a minimal knowledge graph with a few Cypher MERGE commands
▸How-to Everyone
Need to know when a fact was true and when the system believed it
A bitemporal model stores two timestamps on each node or relationship: world validity (when the fact was true in reality) and system validity (when the AI system considered it true). This lets you query both historical truth and the system's belief history, enabling precise fact invalidation and audit trails.
▸How-to Everyone
My markdown notes are scattered
By parsing a directory of markdown files, extracting entities with LLM prompts, and storing them as nodes with timestamps, you create a personal knowledge graph that records when each note was authored/updated, enabling queries like “what did I believe in March versus now”.
▸How-to Everyone
Need to keep old facts without deleting them
Instead of deleting nodes/relationships when information becomes obsolete, set an ‘invalidUntil’ or ‘validTo’ timestamp. This preserves history for audit and lets agents reason about why a fact was superseded.
▸How-to Everyone
Unstructured timestamped logs
Gravity takes episodes (text plus a reference timestamp) and uses an LLM to extract entities, relations, and the associated time interval. It then creates nodes and edges in Neo4j with validity periods, turning unstructured logs into a temporal KG automatically.
▸How-to Everyone
Want to know where someone worked in a given year
Because each edge stores a validity interval, you can ask the graph for information that was true during any historical window. The Gravity search tool translates a natural‑language time constraint into a Cypher range filter.
▸How-to Everyone
Old statements stay in my knowledge graph
When a new episode contradicts an existing fact, Gravity marks the previous edge as ended by setting its 'valid_to' timestamp. This keeps the graph consistent without manual cleanup.
▸How-to Everyone
Need to see how relationships change over time
Graffiti can ingest both structured and unstructured data, automatically creating nodes and edges while attaching start‑end timestamps to each relationship. These validity intervals let the graph record when facts become true and when they are superseded, enabling queries about how information changes over time.
▸How-to Everyone
Find out what I believed in March vs now
Graffiti’s hybrid search combines semantic BM25 scoring with graph‑based distance weighting, and you can restrict queries to a focal node and a specific time window. By specifying the validity interval in the query, the system returns only relationships that were true at that moment, revealing how facts evolved.
The same set on /recipes, filtered by tool and role.
5See also
💬 Discuss this chapter
Ask, share, or report — over on the Heidelberg AI community forum.