Memory Provenance

Visualize the ownership and data-flow story behind your memory — tenants, users, agents, datasets, and files

visualize_memory_provenance() renders the ownership and data-flow story behind your memory — Tenant → User → Agent → Dataset → file, plus agent read/write access and agent-written sessions — to a self-contained HTML file.

Before you start:

• Complete Quickstart to understand basic operations
• Have some ingested data (the projection reads the relational database, so no graph backend is required)

Code in Action

import os
import cognee

# Data must be remembered/loaded into cognee before projecting provenance,
# e.g. via cognee.remember() or cognee.add() + cognee.cognify().
dest = os.path.join(os.path.expanduser("~"), "memory_provenance.html")

await cognee.visualize_memory_provenance(
    destination_file_path=dest,
    include_memory=False,   # when True, fold in extracted entities/relationships
)

This projection is read purely from the relational database — it does not require the graph backend or an LLM, so it works even when the graph database is unavailable. Set include_memory=True to also fold in the extracted entities/relationships (from the relational nodes/edges tables) and link them back to the files they were extracted from.

Raw graph data

If you only need the projected graph data (in the same (nodes, edges) shape the renderer consumes) rather than HTML, call get_memory_provenance_graph():

nodes, edges = await cognee.get_memory_provenance_graph(include_memory=True)

Scoping in multi-tenant deployments

Both functions accept scope_tenant_ids and scope_user_ids to restrict the projection to a tenant or user, and scope_dataset_ids to narrow it to the datasets the caller can read. In multi-tenant deployments you must pass a scope — an unscoped read returns every tenant’s actors, datasets, and files. A tenant scope alone still covers every dataset in the workspace, so for a tenant member who doesn’t administer the tenant also pass scope_dataset_ids; otherwise the graph shows datasets they hold no grant on, along with their files, agents, and sessions. When no scope is given the read is global, which is the intended behavior only for single-user / OSS installs where one user owns everything.

A third argument, scope_dataset_ids, narrows the projection further on top of whichever scope above applies. A tenant scope answers “which datasets exist in this workspace”, which is not the same question as “which datasets may this caller read” — every member of a tenant is in tenant scope. Pass the caller’s readable datasets (from get_all_user_permission_datasets(user, "read")) for any caller who does not administer the tenant:

from cognee.modules.users.permissions.methods import get_all_user_permission_datasets

readable = await get_all_user_permission_datasets(user, "read")

nodes, edges = await cognee.get_memory_provenance_graph(
    scope_tenant_ids=[user.tenant_id],
    scope_dataset_ids=[dataset.id for dataset in readable],
)

scope_dataset_ids only ever narrows — it never widens a tenant or user scope, and an empty list means “this caller may read nothing”, which yields no dataset nodes rather than all of them. Everything the projection derives from datasets narrows with them: the files in those datasets, the ACL grant edges on them, the agents and sessions that worked on them, and the extracted memory when include_memory=True. It also narrows the actor layer — a role is kept only if it holds an ACL grant on an in-scope dataset, and a user only if they own an in-scope dataset, hold a direct grant on one, or belong to a role that does.

Passed without a tenant scope, scope_dataset_ids narrows the Tenant layer too: only the tenants the in-scope datasets belong to are projected, so an unrelated tenant’s name cannot appear in the graph.

Over HTTP

The HTTP endpoints GET /api/v1/schema/provenance (HTML) and GET /api/v1/schema/provenance/json (both take the query param include_memory) scope to the authenticated caller:

Caller	Sees
Tenant administrator — the tenant owner, or a member holding the manage_users capability in the tenant (including through the deprecated admin role-name fallback)	The whole workspace: every dataset, file, role and user in their tenant.
Any other tenant member	Only the datasets they hold a read grant on, plus the files, ACL grants, agents, sessions and memory hanging off them — and only the roles and users tied to those datasets, by the rule scope_dataset_ids applies above.
A caller with no tenant (single-user / OSS, or multi-user without tenants)	The same ACL rule as the row above: the datasets outside any tenant they hold a read grant on — including ones another user shared with them — plus those datasets’ owners, files, ACL grants, agents and sessions. This is exactly the set GET /api/v1/datasets lists, so a dataset they own but hold no read grant on does not appear, and no unrelated tenant is named.

A client that treated the provenance payload as a complete user/role directory must read those lists from the permissions endpoints instead — roles and users — since for a non-administrator it is now scoped to their readable datasets.

Full Example

This script ingests two documents into two datasets, then walks the ownership chain down to the mentions edges that tie each memory node back to the file it came from, prints it as a tree, and renders the same projection to .artifacts/memory_provenance.html. Source: examples/guides/memory_provenance.py.

Memory provenance

import asyncio
import os
from collections import defaultdict

import cognee
from cognee.modules.visualization.cognee_network_visualization import (
    cognee_network_visualization,
)

FLEET_NOTES = "Carlos drives for Echo Global Logistics and files a dispatch log each morning."
DRIVER_NOTES = "Mika is a driver at Landstar. Priya reviews driver records every quarter."


async def main():
    # Prune data and system metadata before running, only if we want "fresh" state.
    await cognee.forget(everything=True)

    # Two datasets so the ownership chain has more than one branch to show.
    await cognee.remember(FLEET_NOTES, dataset_name="fleet_ops", self_improvement=False)
    await cognee.remember(DRIVER_NOTES, dataset_name="driver_records", self_improvement=False)

    # include_memory=True folds in the extracted graph and links it back to source files.
    # No scope_* argument: this is the OSS single-user default, where the one
    # local user owns everything and an unscoped read is the documented,
    # deliberate behavior — not a call site that was missed when scoping was
    # added for multi-tenant deployments. A real API caller should always
    # pass scope_tenant_ids/scope_user_ids/scope_dataset_ids; see
    # get_schema_router.py's _provenance_scope() for how that scope is
    # computed per request.
    nodes, edges = await cognee.get_memory_provenance_graph(include_memory=True)

    name_of = {node_id: properties.get("name") for node_id, properties in nodes}
    type_of = {node_id: properties.get("type") for node_id, properties in nodes}

    # Index targets by (relation, source) so the chain can be walked downwards.
    targets = defaultdict(list)
    for source, target, relation, _properties in edges:
        targets[(relation, source)].append(target)

    print("Provenance chain — who owns what, and which file each memory came from:\n")
    for node_id, properties in nodes:
        if properties.get("type") != "User":
            continue
        print(f"User: {name_of[node_id]}")
        for dataset_id in targets[("owns", node_id)]:
            print(f"  Dataset: {name_of[dataset_id]}")
            for document_id in targets[("contains", dataset_id)]:
                print(f"    File: {name_of[document_id]}")
                mentioned = targets[("mentions", document_id)]
                if not mentioned:
                    print("      (no memory linked — was include_memory=True?)")
                for memory_id in mentioned:
                    print(f"      mentions {type_of[memory_id]}: {name_of[memory_id]}")

    destination = os.path.join(os.path.dirname(__file__), ".artifacts", "memory_provenance.html")
    await cognee_network_visualization((nodes, edges), destination)
    print(f"\nSame graph rendered to {destination}")


if __name__ == "__main__":
    asyncio.run(main())

Graph Visualization

Render your knowledge graph to an interactive HTML file

Schema Inventory

Summarize the knowledge graph by semantic type