memory-molecule 0.1.0

Persistent memory for agentic systems — a faithful transposition of human memory architecture.

memory-molecule

Persistent memory for agentic systems — a faithful transposition of human memory architecture into code.

Installation

pip install memory-molecule

Quickstart

from memory_molecule import MemoryMolecule, MemoryConfig

# Initialize with a vault directory
config = MemoryConfig(vault_path="./my-vault", project="my-project")
mm = MemoryMolecule(config)

# Store a memory
mm.store("Decided to use PostgreSQL for persistence",
         memory_type="decision", importance="foundational")

# Recall memories by concept
results = mm.recall("database persistence")
for r in results:
    print(f"[{r['importance']}] {r['content'][:100]}")

# Apply memory decay (memories fade if not accessed)
report = mm.decay()
print(f"Archived {report.archived_count} stale memories")

# Session lifecycle
bundle = mm.on_session_start()  # Load relevant context
# ... do work ...
mm.on_session_end(commits=["abc123 feat: add auth"], decisions=["Use JWT tokens"])

Tiered Memory Loading

memory-molecule loads context in three tiers to respect token budgets:

from memory_molecule import MemoryLoader, MemoryConfig

loader = MemoryLoader(MemoryConfig(vault_path="./vault"))
result = loader.load(query="authentication", max_tokens=100000)

print(f"Tier 1: {result['tier1']['tokens']} tokens (always loaded)")
print(f"Tier 2: {result['tier2']['tokens']} tokens (recent context)")
print(f"Tier 3: {result['tier3']['tokens']} tokens (on-demand)")

Tier	Target	Contents	Trigger
1	5K tokens	Invariants, latest context, git state	Always
2	50K tokens	Recent sessions, decisions, phase docs	If budget allows
3	150K tokens	Full journals, expertise, knowledge graph	Explicit query

Memory Types

Type	Description	Importance Levels
session	Session journals	context (default)
decision	Architectural decisions	foundational, hard_constraint
expertise	Learned patterns	foundational
knowledge	Domain knowledge	varies

Decay Model

Memories decay exponentially if not accessed:

• Base decay: 0.95^days (half-life ~14 days)
• Importance modifiers: hard_constraint decays 2x slower, tactical decays 1.5x faster
• Access reinforcement: each access boosts relevance by 0.05 (max 0.3)
• Archive threshold: memories below 0.1 relevance are archived (not deleted)

Observation Events

When configured, memory-molecule emits events to an observation server:

• MemoryStore — content written to vault
• MemoryRecall — search performed
• MemoryDecay — decay pass applied
• MemorySessionStart — session initialized
• MemorySessionEnd — session closed

Configure with MemoryConfig(observation_url="http://localhost:4000/events").

API Reference

MemoryMolecule

Method	Returns	Description
store(content, memory_type, importance)	str (path)	Write to vault
recall(query, top_k)	list[dict]	Search by concept
decay()	DecayReport	Apply relevance decay
diff(session_a, session_b)	SessionDiff	Compare sessions
on_session_start()	RecallBundle	Load session context
on_session_end(commits, decisions)	None	Close session
consolidate(session_id)	str	Summarize recent sessions

MemoryLoader

Method	Returns	Description
load_tier1()	dict	Always-load context
load_tier2(days)	dict	Recent relevant context
load_tier3(query)	dict	On-demand deep context
load(query, max_tokens)	dict	Fill tiers to budget

Vision

This package is a community-extractable component of the Oracle agentic engineering system. It implements a faithful transposition of human memory architecture:

Human Memory	Agentic Equivalent	Status
Working memory	Context window	Built-in
Episodic memory	Session journals	Implemented
Semantic memory	Knowledge database	Implemented
Procedural memory	Expertise patterns	Implemented
Consolidation	Compression pass	Implemented
Forgetting curve	Exponential decay	Implemented
Associative recall	Importance-weighted search	Implemented

License

MIT