Package com.tnsai.memory.strategy

Class TieredMemoryStore

java.lang.Object

com.tnsai.memory.strategy.TieredMemoryStore

public final class TieredMemoryStore
extends Object

4-tier memory store with Ebbinghaus-inspired decay and promotion.

Tiers: Working → Episodic → Semantic → Procedural

• Working: raw, high token cost, fast decay
• Episodic: compressed sessions, moderate decay
• Semantic: consolidated facts, slow decay
• Procedural: extracted workflows, near-permanent

Memories gain strength on access (spacing effect) and lose strength over time (decay). Strong memories promote upward; weak memories are evicted.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	TieredMemoryStore.ConsolidationResult	Result of a consolidation cycle.

Constructor Summary

Constructors

Constructor	Description
TieredMemoryStore()

Method Summary

Modifier and Type	Method	Description
MemoryEntry	add(String id, String content)	Adds a new memory at the Working tier.
MemoryEntry	add(String id, String content, MemoryTier tier)	Adds a memory at a specific tier (for loading persisted state).
void	clear()	Clears all memories.
TieredMemoryStore.ConsolidationResult	consolidate()	Runs the consolidation cycle: decay → promote → evict.
List<String[]>	detectContradictions(double threshold)	Detects contradictions: entries with similar content but from different sessions.
Optional<MemoryEntry>	get(String id)	Retrieves a memory by ID and records an access (reinforces strength).
List<MemoryEntry>	getActive(int topK)	Retrieves only active (non-stale, non-superseded) memories.
List<MemoryEntry>	getByTier(MemoryTier tier)	Retrieves all memories at a given tier, sorted by strength descending.
List<MemoryEntry>	getTopK(int k)	Retrieves the top-K strongest memories across all tiers.
boolean	remove(String id)	Removes a memory by ID.
int	size()	Returns total entry count.
MemoryEntry	supersede(String id, String content, String oldId)	Adds a new memory that supersedes an existing one.
Map<MemoryTier,Integer>	tierCounts()	Returns entry count per tier.
List<MemoryEntry>	traceProvenance(String entryId)	Traces provenance: returns the version chain for an entry.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

TieredMemoryStore

public TieredMemoryStore()

Method Details

add

public MemoryEntry add(String id,
 String content)

Adds a new memory at the Working tier.

add

public MemoryEntry add(String id,
 String content,
 MemoryTier tier)

Adds a memory at a specific tier (for loading persisted state).

get

public Optional<MemoryEntry> get(String id)

Retrieves a memory by ID and records an access (reinforces strength).

getByTier

public List<MemoryEntry> getByTier(MemoryTier tier)

Retrieves all memories at a given tier, sorted by strength descending.

getTopK

public List<MemoryEntry> getTopK(int k)

Retrieves the top-K strongest memories across all tiers.

consolidate

public TieredMemoryStore.ConsolidationResult consolidate()

Runs the consolidation cycle: decay → promote → evict.

Returns:

summary of actions taken

supersede

public MemoryEntry supersede(String id,
 String content,
 String oldId)

Adds a new memory that supersedes an existing one. The old entry is marked superseded, its strength halved, and flagged stale. Related entries (same source session) are cascading-stale flagged.

Parameters:

id - new entry ID

content - new content

oldId - ID of the entry being superseded

Returns:

the new entry

detectContradictions

public List<String[]> detectContradictions(double threshold)

Detects contradictions: entries with similar content but from different sessions. Uses Jaccard similarity on word sets. Returns pairs of contradicting entry IDs.

Parameters:

threshold - Jaccard similarity threshold (0.0-1.0, default 0.7)

Returns:

list of contradicting pairs [olderId, newerId]

getActive

public List<MemoryEntry> getActive(int topK)

Retrieves only active (non-stale, non-superseded) memories.

traceProvenance

public List<MemoryEntry> traceProvenance(String entryId)

Traces provenance: returns the version chain for an entry. Follows supersedes links backward to the original.

remove

public boolean remove(String id)

Removes a memory by ID.

size

public int size()

Returns total entry count.

tierCounts

public Map<MemoryTier,Integer> tierCounts()

Returns entry count per tier.

clear

public void clear()

Clears all memories.