Skip to main content
Glama

Supersede

Agent memory that knows which fact is currently in force, and why.

Built for the Relate by Neo4j Hackathon on Relate, the embedded graph database.

The problem

Agents that remember facts from documents hit the same failure: a procedure gets revised, the old revision is still in memory, and the agent happily quotes the stale one. Two documents disagree and the agent picks whichever its retrieval returned first. Vector memory has no notion of "this replaced that" or "this source outranks that one".

Related MCP server: Provenance-Aware Retrieval MCP Server

The idea

Model that structure explicitly as a graph, in-process, with no server:

(Doc {authority})-[:HAS_REV]->(Rev)-[:ASSERTS]->(Fact {subject, predicate, value})
(Rev)-[:SUPERSEDES]->(Rev)
  • Current means "not superseded". It is a graph pattern, not a date comparison.

  • A contradiction exists only between facts in current revisions. A fact from a superseded revision is history, not a conflict.

  • Contradictions are resolved by the authority of the owning document (regulatory > procedure > work instruction). If authority ties, Supersede says unresolved instead of guessing.

  • Every answer carries its reason and the overruled sources.

current_answer("final_inspection", "sampling")
-> {"status": "resolved", "value": "AQL 0.65", "source": "QP-07-r3",
    "reason": "QP-07 (authority 3) outranks the conflicting source(s)",
    "overruled": [{"fact": "F04", "value": "100% inspection", "rev": "WI-12-r1", ...}]}

Why Relate

Relate is an embedded graph database with Cypher, so the supersession chains, the "not superseded" pattern, and the cross-document contradiction join are each a short Cypher query, running in the agent's own process. The store persists on disk between runs.

Quick start

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

python examples/seed_demo.py demo.relate     # small fictional demo knowledge base
python -m pytest -q                          # 9 tests
python examples/mcp_smoke.py demo.relate     # spawns the MCP server and calls it as an agent would

Use it from an MCP client

{
  "mcpServers": {
    "supersede": {
      "command": "python",
      "args": ["-m", "supersede.mcp_server", "--db", "demo.relate"],
      "env": { "PYTHONPATH": "src" }
    }
  }
}

Tools: current_answer, find_contradictions, current_revisions, revision_history.

Relate mode used: persistent on-disk store (--db path; Relate keeps it as a directory), with :memory: as the default for tests. Memory-only would lose the revision history between runs, which is the point of the project.

Design notes

  • Thread affinity. Relate connections are thread-affine (DB-API threadsafety = 1), and an MCP server calls tools from worker threads. Store runs all database work on one dedicated thread; a regression test covers it.

  • Stale facts. An early version of the contradiction query compared facts across all revisions and flagged superseded ones. The current query excludes them, and a test pins that behavior.

Disclosures (per the contest rules)

  • Started: 21 November 2026, inside the contest period. No pre-existing project is submitted.

  • Reused code: none copied. The concepts (document authority hierarchy, SUPERSEDES chains, contradiction detection) come from the author's earlier GraphRAG work; this implementation was written from scratch for Relate.

  • Data: all demo data is fictional and written for this repo. No client or third-party documents.

  • AI tools: the code, tests and this README were developed with substantial assistance from Claude (Anthropic). The author directed the design and is responsible for the result.

  • Third-party: Relate (relate-db 1.2.0, Apache-2.0) and the MCP Python SDK.

License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides agents with durable, provenance-aware memory through tools for remembering, recalling, answering, and maintaining information, while structurally resisting injection and confabulation.
      470 PyPI
      11
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to query a single-source ontology of types, entities, statements, evidence, and controlled vocabulary, including bitemporal "as of" and "as recorded" fact lookups. Supports writing by letting agents propose candidate statements while keeping approval, review transitions, and authoritative reasoning restricted to approved facts.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to record facts with declared sources, search or list current and superseded memories, and correct entries while preserving version history and rejecting stale writes.
      MIT