[Feature]: Temporal freshness policies for stale and superseded memories

[moritzscheele]

Problem Statement

Cognee already supports temporal ingestion and SearchType.TEMPORAL, which is useful for asking what happened before/after/between dates. In agent-memory use cases, there is a related but distinct problem: older memories can remain highly retrievable even after a newer memory supersedes them.

For example, a customer, user, project, or workflow preference may change over time:

• "Customer 55442 prefers delivery address A" was true in March.
• "Customer 55442 prefers delivery address B" is approved in June.
• A future agent asks for the current preference and receives both, or the older one wins by semantic similarity.

The memory graph preserves useful history, but applications also need a deterministic way to identify current vs stale facts and avoid feeding outdated facts to agents as if they were still authoritative.

Proposed Solution

Add an optional temporal freshness / supersession layer for memories. This would complement the existing temporal graph rather than replace it.

At a high level:

1. Allow callers to attach structured validity metadata to remembered facts, such as entity, predicate, object type/id, valid_from, valid_to, transaction time, confidence, source, and status.
2. Support a supersession policy for facts that share the same memory key, for example newer_conflicting_fact or latest_per_key.
3. Preserve historical facts in the graph, but mark older superseded facts as stale/inactive or exclude them from current-memory retrieval.
4. Add retrieval options that can prefer or require current facts while still allowing timeline queries.
5. Expose enough metadata in results for applications to explain why a fact is current, stale, superseded, or historical.

A possible API shape:

await cognee.remember(
    "Customer 55442 prefers delivery address B for standard orders.",
    dataset_name="customer_memory",
    temporal_cognify=True,
    memory_key={
        "entity": "customer:55442",
        "predicate": "prefers_delivery_address",
        "object_type": "delivery_address",
    },
    valid_from="2026-06-07T00:00:00Z",
    supersedes_policy="newer_conflicting_fact",
)

result = await cognee.recall(
    query_type=SearchType.TEMPORAL,
    query_text="Current delivery preference for customer 55442",
    datasets=["customer_memory"],
    freshness_policy="current",
)

Alternatives Considered

• Only use SearchType.TEMPORAL: this helps with time-window retrieval, but does not by itself adjudicate which remembered fact is currently valid.
• Let each application maintain its own lifecycle ledger: this works, but many Cognee agent-memory users will hit the same stale-memory problem.
• Delete old memories: this loses historical context, auditability, and the ability to answer timeline questions.
• Use recency weighting only: useful, but insufficient when an older fact remains semantically closer or when a newer fact is merely related rather than truly superseding.

Use Case

We are using Cognee as operational memory for order-processing agents. Human-approved customer/article mappings and customer preferences are remembered so future orders can benefit from prior decisions.

Customer preferences can change. We want to preserve history while ensuring that future agents are not confidently given stale operational facts. The same pattern applies to user preferences, project rules, API behavior, contact details, addresses, pricing terms, and workflow decisions.

Implementation Ideas

This could be implemented incrementally:

1. Add a lightweight memory validity metadata model for remembered facts.
2. Store validity metadata in graph/vector metadata without requiring every user to opt in.
3. Add a resolver that groups candidate facts by a stable memory key and determines current/stale/superseded state.
4. Add retrieval-time filtering/ranking options such as freshness_policy="all" | "current" | "prefer_current" | "historical".
5. Wire the policy through retriever_specific_config first, especially for TemporalRetriever, before deciding whether it belongs in the public top-level API.
6. Add tests that prove: newer conflicting memories supersede older ones, stale memories remain queryable for historical/timeline queries, current-only recall excludes stale facts, and results expose freshness metadata.

I created a proposal branch in a fork with a more detailed design sketch and can turn it into a PR if this direction is useful.

Additional Context

The current Cognee temporal guide already covers event/time extraction and temporal recall. This feature request is specifically about temporal validity and stale-memory governance on top of that foundation.

Pre-submission checklist:

• I have searched existing issues to ensure this feature hasn't been requested already.
• I have provided a clear problem statement and proposed solution.
• I have described my specific use case.

[moritzscheele]

I opened a draft proposal PR with a design sketch here: #3005. I adjusted the proposal after reading through Graphiti's temporal context graph model, especially validity windows (valid_at / invalid_at), source episodes/provenance, and invalidation of contradicted facts instead of deletion.

[moritzscheele]

Following up from #3005: I’ll try the Global Context Index recommendation first.

My current understanding is:

• Global Context Index should help when the answer depends on the broader shape of a dataset, especially evolving conversations/project memory/current status.
• It may be a practical solution for some “what is the current state?” questions because graph completion can see a compact dataset-level orientation before local evidence.
• The remaining thing I want to validate is whether it deterministically prevents superseded facts from being returned as current truth, or whether it improves synthesis while still leaving stale/current adjudication to the caller/application.

I’ll test this against the concrete stale preference case from the issue: old customer preference A, newer approved customer preference B, then a query for the current preference. If Global Context Index handles that cleanly, this feature request may just need documentation/example guidance. If not, the narrower gap is probably validity-window / invalidation metadata rather than broader context retrieval.

[moritzscheele]

I did a code-level pass through the Global Context Index path after your suggestion.

What I found:

• Build path: improve(..., build_global_context_index=True) runs global_context_index_pipeline(...) after the normal memify enrichment, using graph bucketing by default in improve.
• Retrieval path: SearchType.GRAPH_COMPLETION can opt in with retriever_specific_config={"include_global_context_index": True, "global_context_index_top_k": 3}.
• Effect at retrieval time: GraphCompletionRetriever.get_context_from_objects() prepends the formatted root/top GlobalContextSummary texts as a World summary / Relevant areas prelude before the normal resolved triplet context.

So I agree Global Context Index is the first thing to try for the stale preference use case. It may be enough when the summary captures the newer state and guides synthesis toward the current answer.

The narrower gap I still see is that this does not appear to add deterministic current-vs-superseded semantics to the underlying facts. Older contradictory triplets can still exist and be retrieved; GCI adds higher-level context, but I do not see validity-window fields or filtering like valid_at / invalid_at / expired_at, nor an invalidation step that marks older contradictory facts as no longer current.

That suggests the practical split may be:

1. Use Global Context Index for broad current-state synthesis.
2. If applications need auditable “current fact only” behavior, add a separate temporal validity/invalidation layer or document that stale/current adjudication remains application-owned.

A concrete validation scenario would be:

1. Remember: “On 2026-01-01, Customer A prefers delivery method X.”
2. Remember later: “On 2026-03-01, Customer A now prefers delivery method Y instead of X.”
3. Build the Global Context Index.
4. Query with GRAPH_COMPLETION + include_global_context_index=True: “What is Customer A’s current delivery preference?”
5. Check both the generated answer and only_context=True output to see whether old preference X still appears as equally current evidence or is clearly superseded by Y.

If that scenario reliably returns Y and contextualizes X as historical, this issue can probably become a documentation/example request. If X still appears as current evidence, then the remaining feature request is specifically validity-window metadata and stale-fact invalidation, not global context.