autourgos-episodic-memory

Structured task/outcome log for Autourgos agents. Unlike the freeform conversational recall the rest of the memory family provides, EpisodicMemory records what was tried and what happened — so a future run can check "have I attempted this before, and did it work?" before repeating a known-bad approach.

from autourgos_episodic_memory import EpisodicMemory

memory = EpisodicMemory(db_path="episodes.db")  # persists across restarts

memory.remember(
    task="Deploy the app to production",
    outcome="fail",
    actions_taken=["ran deploy.sh", "hit permission error on S3 bucket"],
    notes="Needs IAM role update before retrying.",
)

for episode in memory.retrieve("deploying the app", top_k=3):
    print(episode.metadata["outcome"], "-", episode.content)

Table of Contents

• Install
• Why a separate package
• Quick Start
• Constructor Reference
• License

Install

pip install autourgos-episodic-memory

Depends on autourgos-memory and autourgos-semantic-memory (its TF-IDF KeywordRetriever does the relevance scoring — this package doesn't reimplement it). SQLite persistence is stdlib, no extra dependency.

Why a separate package

The rest of the memory family stores conversation (what was said). EpisodicMemory stores attempts (what was done and whether it worked) — a different shape of data with its own outcome field ("success" / "fail" / "partial") and actions_taken list, not a chat turn. Keeping it separate from autourgos-vector-memory/autourgos-semantic-memory avoids conflating "recall a relevant past conversation" with "recall a relevant past task result."

Quick Start

from autourgos_episodic_memory import EpisodicMemory

memory = EpisodicMemory(db_path="agent_episodes.db", max_episodes=500)

memory.remember(
    task="Fix the failing test suite",
    outcome="success",
    actions_taken=["reran pytest -x", "found stale fixture", "regenerated fixture"],
)

memory.remember(
    task="Fix the failing test suite",
    outcome="fail",
    actions_taken=["tried deleting __pycache__"],
    notes="Did not address the root cause.",
)

# Before trying again, check what happened last time:
past = memory.retrieve("failing test suite", top_k=5)
for ep in past:
    print(f"[{ep.metadata['outcome']}] {ep.metadata['task']}")

db_path=":memory:" (the default) keeps everything in RAM for the process lifetime. Pass a real file path for recall across restarts — episodes are reloaded and re-indexed on the next EpisodicMemory(db_path=...) construction.

EpisodicMemory supports the context-manager protocol, closing its connection automatically:

with EpisodicMemory(db_path="agent_episodes.db") as memory:
    memory.remember(task="Deploy the app", outcome="success")
# connection is closed here automatically

Constructor Reference

EpisodicMemory

EpisodicMemory.remember(task, outcome, actions_taken=None, notes="")

Returns an Episode (frozen dataclass with task/outcome/actions_taken/notes/timestamp).

EpisodicMemory.retrieve(query, top_k=5)

Returns a list of autourgos_memory.Document, ranked by TF-IDF relevance to query. Each Document.metadata carries task, outcome, actions_taken, notes, timestamp.

License

Apache License 2.0 — see LICENSE.