Episodic Replay

from dakera import BatchMemoryFilter, BatchRecallRequest, DakeraClient
import uuid
from typing import Literal

client = DakeraClient(base_url="http://localhost:3000", api_key="dk-...")

Role = Literal["user", "agent"]
Significance = Literal["normal", "hypothesis", "error", "decision", "solution", "breakthrough"]

IMPORTANCE_BY_SIGNIFICANCE = {
    "normal": 0.72,
    "hypothesis": 0.75,
    "error": 0.80,
    "decision": 0.92,
    "solution": 0.95,
    "breakthrough": 0.97,
}
KEY_TURNS = {"decision", "solution", "breakthrough"}

class EpisodicSession:
    """Records a conversation episode with full replay capability."""

    def __init__(self, agent_id: str, session_id: str = None):
        self.agent_id = agent_id
        self.session_id = session_id or f"sess-{uuid.uuid4().hex[:8]}"
        self.sequence = 0

    def record(self, role: Role, content: str, significance: Significance = "normal") -> dict:
        """Store one interaction turn."""
        self.sequence += 1
        return client.store_memory(
            agent_id=self.agent_id,
            content=f"[{role}] {content}",
            memory_type="episodic",
            importance=IMPORTANCE_BY_SIGNIFICANCE[significance],
            # The session ID is a tag because batch filters match tags, not metadata
            tags=["episode", self.session_id, f"role:{role}", significance],
            metadata={"session_id": self.session_id, "sequence": self.sequence,
                      "role": role, "significance": significance}
        )

    def _turns(self) -> list:
        """Every turn of this session, in sequence order (filter-based, no query)."""
        resp = client.batch_recall(BatchRecallRequest(
            agent_id=self.agent_id,
            filter=BatchMemoryFilter(tags=[self.session_id]),
            limit=200
        ))
        return sorted(resp.memories, key=lambda m: m.metadata["sequence"])

    def replay_full(self) -> list[str]:
        """Replay all turns in this session, in order."""
        return [m.content for m in self._turns()]

    def replay_decisions_only(self) -> list[str]:
        """Replay only decisions, solutions and breakthroughs, in order."""
        return [m.content for m in self._turns() if m.metadata["significance"] in KEY_TURNS]

# --- Record the debugging session ---
session = EpisodicSession("codeassist-dev-7", "sess-20260519")

session.record("user",
    "TypeError: cannot read property 'length' of undefined in parser.js:42",
    significance="error"
)
session.record("agent",
    "Likely a null check missing. Try: if (arr && arr.length) before accessing.",
    significance="hypothesis"
)
session.record("user",
    "Still failing on the same line. I already had that null check.",
    significance="normal"
)
session.record("agent",
    "Root cause: fetchData() at line 38 is not awaited. Async race condition. Add 'await' before the call.",
    significance="decision"
)
session.record("user",
    "That was it! Adding await before fetchData() fixed the TypeError. Tests all green.",
    significance="solution"
)

# --- Replay later (new process, resuming work) ---
replay_session = EpisodicSession("codeassist-dev-7", "sess-20260519")

print("=== FULL REPLAY ===")
for turn in replay_session.replay_full():
    print(turn)

print("\n=== DECISIONS ONLY ===")
for turn in replay_session.replay_decisions_only():
    print(turn)

# Output (decisions only):
# [agent] Root cause: fetchData() at line 38 is not awaited. Async race condition. Add 'await' before the call.
# [user] That was it! Adding await before fetchData() fixed the TypeError. Tests all green.

import { DakeraClient } from '@dakera-ai/dakera';
import { randomUUID } from 'crypto';

const client = new DakeraClient({ baseUrl: 'http://localhost:3000', apiKey: 'dk-...' });

type Role = 'user' | 'agent';
type Significance = 'normal' | 'hypothesis' | 'error' | 'decision' | 'solution' | 'breakthrough';

const IMPORTANCE: Record<Significance, number> = {
  normal: 0.72,
  hypothesis: 0.75,
  error: 0.80,
  decision: 0.92,
  solution: 0.95,
  breakthrough: 0.97,
};
const KEY_TURNS = new Set<string>(['decision', 'solution', 'breakthrough']);

class EpisodicSession {
  private agentId: string;
  private sessionId: string;
  private seq = 0;

  constructor(agentId: string, sessionId?: string) {
    this.agentId = agentId;
    this.sessionId = sessionId ?? `sess-${randomUUID().slice(0, 8)}`;
  }

  get id(): string { return this.sessionId; }

  async record(role: Role, content: string, sig: Significance = 'normal'): Promise<void> {
    this.seq += 1;
    await client.storeMemory(this.agentId, {
      content: `[${role}] ${content}`,
      memory_type: 'episodic',
      importance: IMPORTANCE[sig],
      // The session ID is a tag because batch filters match tags, not metadata
      tags: ['episode', this.sessionId, `role:${role}`, sig],
      metadata: { session_id: this.sessionId, sequence: this.seq, role, significance: sig },
    });
  }

  // Every turn of this session in sequence order (filter-based, no query)
  private async turns() {
    const resp = await client.batchRecall({
      agent_id: this.agentId,
      filter: { tags: [this.sessionId] },
      limit: 200,
    });
    if (resp.truncated) console.warn('Session has more than 200 turns; raise the limit');
    return [...resp.memories].sort(
      (a, b) => Number(a.metadata?.sequence ?? 0) - Number(b.metadata?.sequence ?? 0)
    );
  }

  async replayFull(): Promise<string[]> {
    return (await this.turns()).map(m => m.content);
  }

  async replayDecisionsOnly(): Promise<string[]> {
    return (await this.turns())
      .filter(m => KEY_TURNS.has(String(m.metadata?.significance)))
      .map(m => m.content);
  }
}

// Record
const session = new EpisodicSession('codeassist-dev-7', 'sess-20260519');
await session.record('user', "TypeError: cannot read property 'length' of undefined in parser.js:42", 'error');
await session.record('agent', 'Likely a null check missing. Try: if (arr && arr.length) before accessing.', 'hypothesis');
await session.record('user', 'Still failing on the same line. I already had that null check.');
await session.record('agent', "Root cause: fetchData() at line 38 is not awaited. Add 'await' before the call.", 'decision');
await session.record('user', 'That was it! Adding await fixed the TypeError. Tests all green.', 'solution');

// Replay later
const replay = new EpisodicSession('codeassist-dev-7', 'sess-20260519');
console.log('=== FULL REPLAY ===');
(await replay.replayFull()).forEach(t => console.log(t));
console.log('\n=== DECISIONS ONLY ===');
(await replay.replayDecisionsOnly()).forEach(t => console.log(t));

use dakera_client::{
    BatchMemoryFilter, BatchRecallRequest, DakeraClient, MemoryType, StoreMemoryRequest,
};
use serde_json::json;

let client = DakeraClient::builder("http://localhost:3000").api_key("dk-...").build()?;
let agent_id = "codeassist-dev-7";
let session_id = "sess-20260519";

// (role, content, significance, importance)
let turns = vec![
    ("user", "TypeError: cannot read property length of undefined in parser.js:42", "error", 0.80f32),
    ("agent", "Likely null check missing. Try: if (arr && arr.length) before accessing.", "hypothesis", 0.75),
    ("user", "Still failing. Already tried the null check.", "normal", 0.72),
    ("agent", "Root cause: fetchData() not awaited at line 38. Async race. Add await.", "decision", 0.92),
    ("user", "Fixed! Tests all green. Shipping to staging.", "solution", 0.95),
];

// Store all turns: session ID as a tag, sequence number in metadata
for (seq, (role, content, significance, importance)) in turns.iter().enumerate() {
    client.store_memory(
        StoreMemoryRequest::new(agent_id, format!("[{}] {}", role, content))
            .with_type(MemoryType::Episodic)
            .with_importance(*importance)
            .with_tags(vec!["episode".into(), session_id.into(), format!("role:{}", role), significance.to_string()])
            .with_metadata(json!({ "session_id": session_id, "sequence": seq + 1, "significance": significance })),
    ).await?;
}

// Replay: list the session's turns by tag (no query), then sort by sequence
let listed = client.batch_recall(
    BatchRecallRequest::new(agent_id)
        .with_filter(BatchMemoryFilter::default().with_tags(vec![session_id.into()]))
        .with_limit(200),
).await?;

let sequence = |m: &dakera_client::RecalledMemory| {
    m.metadata.as_ref().and_then(|v| v["sequence"].as_u64()).unwrap_or(0)
};
let mut memories = listed.memories;
memories.sort_by_key(|m| sequence(m));

for m in &memories {
    println!("{}", m.content);
}

package main

import (
    "context"
    "fmt"
    "log"
    "sort"

    dakera "github.com/dakera-ai/dakera-go"
)

type Turn struct {
    Role         string
    Content      string
    Significance string
    Importance   float32
}

// sequence reads the turn number stored in metadata (JSON numbers decode as float64)
func sequence(m dakera.RecalledMemory) float64 {
    n, _ := m.Metadata["sequence"].(float64)
    return n
}

func main() {
    client := dakera.NewClientWithOptions(dakera.ClientOptions{
        BaseURL: "http://localhost:3000",
        APIKey:  "dk-...",
    })
    ctx := context.Background()
    agentID := "codeassist-dev-7"
    sessionID := "sess-20260519"

    turns := []Turn{
        {"user", "TypeError: cannot read property length of undefined in parser.js:42", "error", 0.80},
        {"agent", "Likely null check missing. Try: if (arr && arr.length) before accessing.", "hypothesis", 0.75},
        {"user", "Still failing. Already tried the null check.", "normal", 0.72},
        {"agent", "Root cause: fetchData() at line 38 not awaited. Async race. Fix: add await.", "decision", 0.92},
        {"user", "Fixed! Tests green. Shipping to staging.", "solution", 0.95},
    }

    // Record all turns: session ID as a tag, sequence number in metadata
    for i, t := range turns {
        importance := t.Importance
        if _, err := client.StoreMemory(ctx, agentID, dakera.StoreMemoryRequest{
            Content:    fmt.Sprintf("[%s] %s", t.Role, t.Content),
            MemoryType: "episodic",
            Importance: &importance,
            Tags:       []string{"episode", sessionID, "role:" + t.Role, t.Significance},
            Metadata: map[string]interface{}{
                "session_id":   sessionID,
                "sequence":     i + 1,
                "significance": t.Significance,
            },
        }); err != nil {
            log.Fatal(err)
        }
    }

    // Replay: list the session's turns by tag (no query), then sort by sequence
    listed, err := client.BatchRecall(ctx, dakera.BatchRecallRequest{
        AgentID: agentID,
        Filter:  dakera.BatchMemoryFilter{Tags: []string{sessionID}},
        Limit:   200,
    })
    if err != nil {
        log.Fatal(err)
    }
    sort.Slice(listed.Memories, func(i, j int) bool {
        return sequence(listed.Memories[i]) < sequence(listed.Memories[j])
    })
    for _, m := range listed.Memories {
        fmt.Println(m.Content)
    }
}