memory-hierarchy-management

Memory Hierarchy Management (MemGPT-Style)

Context

With 43+ skills and growing, stuffing everything into the agent's context window is impossible and wasteful. The naive approach (read SKILL.md on demand) is slow and lossy. This skill provides a 3-layer memory architecture: Working Memory (limited, in-context), Archival Store (unlimited, OKF-indexed), Long-term Storage (filesystem). Recall is multi-strategy (keyword + importance + recency + frequency).

The core insight: context is RAM, vault is disk. We treat them differently.

Guidance

The 3 Layers

Working Memory (in-context, ≤8000 chars)
    ↑↓ auto-promote / LRU evict
Archival Store (OKF graph, unlimited)
    ↑↓ write to filesystem on persist
Long-term Storage (docs/ml-agent-memory/auto-search/)

When to Recall

from framework.src.memory import MemoryHierarchy

mem = MemoryHierarchy(okf_dir="docs/ml-agent-memory")
mem.bootstrap(extra_dirs=["skills/examples", "docs"])

# At decision points — recall relevant skills
items = mem.recall("time series walk-forward validation", k=5)
for item in items:
    print(f"[{item.type}] {item.id} (imp={item.importance})")

When to Remember

from framework.src.memory import MemoryItem

# High-importance → auto-archive
mem.remember(MemoryItem(
    id="auto-finding-2026-08-05-catboost-vs-xgboost",
    content="In S6E2, CatBoost OOF 0.8124 beat XGBoost 0.8003 (+0.012)",
    type="experiment",
    importance=0.8,
    tags=["tabular","catboost","s6e2"],
), persist=True)

Multi-Strategy Recall (Advanced)

from framework.src.memory.recall import multi_strategy_recall, RecallConfig

cfg = RecallConfig(
    use_keyword=True,
    use_recency=True,       # Decay old items
    use_importance=True,    # Promote high-imp
    use_access_frequency=True,  # Frequently-used stays
    recency_decay_days=30,
    final_top_k=5,
)
results = multi_strategy_recall(mem.archival, "tabular feature engineering", cfg)