docs/memory.md

memory.md — LifeStackMemory Reference

agent/memory.py — ChromaDB-backed trajectory and human-feedback storage.

---

Overview

LifeStackMemory persists two types of data:

Collection	What's stored
collection (trajectories)	Successful episode decisions — action type, reward, reasoning
feedback_collection	Real-world outcome feedback submitted via the Follow-up tab

Only trajectories with total_reward >= 2.0 are stored (threshold prevents noise).

---

API

Instantiation

from agent.memory import LifeStackMemory

memory = LifeStackMemory(silent=True)           # default path
memory = LifeStackMemory(silent=True, path="./my_memory")  # custom path

The module-level singleton in app.py is named MEMORY:

MEMORY = LifeStackMemory(silent=True)

store_trajectory(...)

memory.store_trajectory(
    conflict_title="Friday 6PM",
    route_taken="communicate",
    total_reward=2.5,
    metrics_diff_str="career.workload: -15.0",
    reasoning="Delegating resolved workload spike",
)

Silently skips storage if total_reward < 2.0.

store_feedback(feedback: OutcomeFeedback)

from core.feedback import OutcomeFeedback

feedback = OutcomeFeedback(
    episode_id="A1B2C3D4",
    overall_effectiveness=8,
    domains_improved=["career", "mental_wellbeing"],
    domains_worsened=[],
    unexpected_effects="Felt more confident",
    resolution_time_hours=2.0,
)
memory.store_feedback(feedback)

Used by the Follow-up tab in app.py.

get_stats() -> dict

stats = memory.get_stats()
# {
#   "total_memories": 42,
#   "average_reward": 2.71,
#   "by_action_type": {"communicate": 18, "delegate": 12, ...}
# }

query(conflict_description, n_results=3) -> list[dict]

Retrieves the most semantically similar past decisions for a given situation description.

---

Change Log

Date	Change
2026-04-23	AGENT_MEMORY reference in app.py corrected to MEMORY (the actual singleton)