⚙️ FEATURE: Experiential memory — index past session traces to seed future context

[FernandoCelmer]

Problem

pycodeloop appends structured JSONL traces to ~/.pycodeloop/logs/<session_key>.jsonl but never reads them back. Each session starts cold with no knowledge of what worked or failed in past runs. Agents based on ExpeL, Voyager, and MemGPT architectures demonstrate that replaying and indexing prior execution traces significantly improves performance on repeated or related tasks.

Context

The "Code as Agent Harness" literature (arXiv 2605.18747) and curated papers (ExpeL, Voyager) show that experiential memory — a searchable index of past agent runs — enables lifelong learning without fine-tuning. When the agent starts a new session, relevant prior traces are injected as few-shot context, teaching the agent what tools and strategies succeeded for similar tasks.

Expected behavior

codeloop = CodeLoop(config=Config(
    recall=True,           # search past traces before first turn
    recall_top_k=3,        # inject top-3 most relevant past sessions
))

Internally:

1. On session start, ExperientialMemory.search(prompt) queries past JSONL traces by keyword or embedding similarity
2. Top-K matching traces are summarized and prepended to the system prompt as: # Past relevant runs\n...
3. After session ends, the trace is indexed for future retrieval

Suggested implementation

• Add ExperientialMemory class in pycodeloop/store/experiential_memory.py
• Storage: SQLite FTS5 table (session_key, prompt, summary, tool_names, outcome) — keyword search first, embedding search as optional upgrade
• summarize_trace(jsonl_path) -> str — pure function, extracts key decisions and outcomes from JSONL
• Add recall: bool = False, recall_top_k: int = 3 to Config
• Wire into CodeLoop.run(): search before first turn, index after last turn

References

• "Code as Agent Harness" — arXiv 2605.18747
• ExpeL: Learning from Execution-Based Feedback
• Voyager: An Open-Ended Embodied Agent with Large Language Models