Lifecycle and Hierarchy

Mneno preserves memory history instead of silently deleting or overwriting it. Conflict resolution and hierarchy transitions are deterministic, local, and recorded in each memory’s audit trail.

Memory statuses

Memories use four lifecycle statuses:

active: available for normal retrieval
superseded: replaced by a newer memory but retained for history
archived: retained but excluded from default retrieval
conflicted: linked to another memory with an unresolved contradiction

Search and context building exclude archived and superseded memories by default. Conflicted memories remain visible by default with conflict reasons, so contradictory facts are not silently hidden. Use explicit inactive-inclusion options only when you need historical records.

Detect conflicts while adding

Conflict detection runs automatically by default. Use add_with_report() when you need the reports and resolution actions.

from mneno import MemoryClient

client = MemoryClient()
client.add("User prefers Python 3.10.", memory_type="preference")

result = client.add_with_report(
    "User now prefers Python 3.11.",
    memory_type="preference",
)

for report in result.conflict_reports:
    print(report.conflict_type, report.reason, report.suggested_action)

print(result.resolution_actions)

Mneno never deletes memories during conflict resolution. Supersession links the old memory through superseded_by, while contradictions use conflicts_with links. A contradiction is not an update unless the new memory contains an explicit update signal such as now, changed to, updated to, no longer, from now on, correction:, actually, previously ... now ..., or supersedes. Examples:

User prefers Python 3.10. plus User now prefers Python 3.11. creates supersession.
User prefers CLI. plus User wants MCP. creates a conflict, not silent supersession.

Detect without mutating storage

reports = client.detect_conflicts("User does not prefer Python.")

Use client.list_conflicts() to reconstruct stored conflict reports from audit history.

Memory layers

Mneno organizes memories into these layers:

short_term
working
episodic
semantic
operational
archived

Operational, working, and semantic memories receive higher default retrieval priority. Retention decisions use transparent signals such as importance, access count, recency, memory type, status, and current layer.

Evaluate hierarchy transitions

result = client.evaluate_hierarchy()

print("Promoted:", [memory.id for memory in result.promoted])
print("Demoted:", [memory.id for memory in result.demoted])
print("Archived:", [memory.id for memory in result.archived])

Hierarchy evaluation archives rather than deletes. Every transition adds an audit event.

Manual transitions

memory = client.add("Repeatedly useful project fact.", layer="short_term")

episodic = client.promote_memory(memory.id, "episodic")
semantic = client.promote_memory(episodic.id, "semantic")
demoted = client.demote_memory(semantic.id, "episodic")

Invalid layer transitions raise a clear error. Use client.list_by_layer("semantic") to inspect one layer.

Getting Started

Core Concepts

Advanced

Lifecycle and Hierarchy

Memory statuses

Detect conflicts while adding

Detect without mutating storage

Memory layers

Evaluate hierarchy transitions

Manual transitions

​Memory statuses

​Detect conflicts while adding

​Detect without mutating storage

​Memory layers

​Evaluate hierarchy transitions

​Manual transitions

Memory statuses

Detect conflicts while adding

Detect without mutating storage

Memory layers

Evaluate hierarchy transitions

Manual transitions