diff --git a/docs/prds/session-memory-curator.md b/docs/prds/session-memory-curator.md new file mode 100644 index 000000000..46b4f3e7b --- /dev/null +++ b/docs/prds/session-memory-curator.md @@ -0,0 +1,195 @@ +# Persistent session-memory curator (reference implementation) -- decision + +**Status:** Approved for archie-core-1786637499114 implementation +**Date:** 2026-09-02 +**Beads issue:** `archie-core-1786637499114` +**Parent epic:** `archie-core-1786637500725` (curator engine) +**Depends on:** `archie-core-1786637499636` (bind curators to memory +engines, shipped) and the `domain/memory` engine family (shipped) + +## Decision + +Each pass: find sessions with activity since the last pass, ask the +model to extract a short list of durable observations from each one's +recent messages, and write each through the curator's bound memory +engine. Extraction is **scoped to one session** -- `Observation.Identity` +is the session ID, not a user or cross-session identity. No +consolidation across sessions, no forgetting, no rewriting a prior +extraction: every pass only adds. + +This is the second contract consumer the epic asks for, and the one that +exercises the curator/memory-engine binding +(`archie-core-1786637499636`) for real, unlike the skill curator, which +declares no memory engine at all. + +## Why session-scoped, not user- or agent-wide + +`docs/architecture/migration-decisions.md#5` lists the four required +memory scopes (global, agent-wide, user-wide, agent-user relationship) +as **still open** -- there is no decided mapping yet from a chat session +to a durable identity that would outlive that session (a Telegram chat +ID is not necessarily "the same person" as a web session; per-platform +identity resolution does not exist as a memory concern today). Choosing +session-as-identity sidesteps a decision this issue has no business +making unilaterally: it is the narrowest scope that is unambiguous +(`gateway.SessionContext.SessionID` already exists, is already unique, +and already has no cross-platform identity claim attached to it), and +it is forward-compatible -- widening to a resolved user identity later +is a change to what `Identity` is populated with, not to the +extraction or write path. + +## Why a new `curator.ConversationSource`, not `gateway.SessionStore` directly + +`internal/domain/curator` is a domain package; `internal/gateway` is not +one of `internal/domain/*`'s dependencies by convention, and +`gateway.SessionStore`'s full CRUD surface (branch, fork, replace, +search) is far more than a curator needs or should be able to reach -- +the same reasoning `ToolBuilder`/`SkillStore`/`MemoryEngineSource` +already established for every other host service this package depends +on. `curator.ConversationSource` is a two-method read-only interface; +`internal/app/archied` adapts the real `gateway.SessionStore` to it, the +same shape `MemoryEngineSource` already uses for +`domain/memory.Registry`. + +```go +// ConversationSource is read-only conversation history, narrowed to +// what a curator needs to review recent activity -- never the full +// session CRUD/branch/search surface a chat gateway exposes. +type ConversationSource interface { + // RecentSessions returns every session touched at or after since, + // newest first. + RecentSessions(ctx context.Context, since time.Time) ([]SessionSummary, error) + // Messages returns the most recent n messages of one session, in + // chronological order. + Messages(ctx context.Context, sessionID string, n int) ([]ConversationMessage, error) +} + +type SessionSummary struct { + ID string + LastActive time.Time +} + +type ConversationMessage struct { + Role string // "user" or "assistant" + Content string + At time.Time +} +``` + +`Manifest` gains `Conversations bool`, gated exactly like `Skills`: +`Registry.validateDeclared` requires a `ConversationSource` on the host +when declared, `Registry.filter` clears it from a curator's view when +not. Role is derived the same way `gateway.compressTurnHistory` already +does (`message.From == botUser` -> `"assistant"`, else `"user"`) -- +copied logic, not shared code, since the source type +(`gateway.Message`) is exactly the thing this package must not import. + +## Extraction shape + +`Pass`: + +1. `Conversations.RecentSessions(ctx, effectiveSince(in.Since))` -- see + below for the zero-`Since` default. +2. For each session, `Conversations.Messages(ctx, id, 40)` -- the last + 40 messages, not the full history. A session accumulates far more + history than a skill file accumulates content; unlike the skill + curator's "re-read everything, it's cheap," a full-history read here + is not cheap and is not needed -- durable facts worth keeping surface + in recent exchanges, and a 40-message tail is deliberately generous + against the model's own context rather than tuned tightly, since + getting this number exactly right is not this issue's job. +3. One model call per session: the message tail, plus an instruction to + return a JSON array of short strings, each one fact/preference/ + correction worth keeping, or `[]` if nothing is. Capped at 5 items + per session per pass -- a session that produced more than 5 durable + facts in one pass is the extraction prompt's problem to get more + precise about, not a limit this curator should quietly lift. +4. A response that isn't valid JSON, or that fails to parse, is treated + as "nothing extracted" for that session, not a pass failure -- the + next pass tries again, and this is a curator, not a build gate. +5. Each extracted string becomes one `Write` through + `Registrar.MemoryEngines.Get("builtin")` + (`Observation{Identity: sessionID, Kind: "note", Content: text}`). + One `Action` per session summarizes the count and lists the session + ID; a session with nothing extracted gets no `Action`, matching the + skill curator's "a pass with nothing to report is not an error, and + not every subject needs an entry every time." + +`effectiveSince`: `PassInput.Since` zero (first pass, or the runtime +declining to name a horizon) resolves to 24 hours before now, not "the +beginning of time." Extracting from a session's entire history on the +very first pass is exactly the kind of unbounded-cost-on-cold-start +mistake `Check` exists to keep cheap, and 24h is long enough to catch +what a daily check-in cadence would have caught anyway. + +`Check`: `len(RecentSessions(ctx, effectiveSince(zero-Since))) > 0` -- +cheap (no model call), and answers "is there anything a pass would find" +honestly rather than always returning true. + +## What we deliberately do NOT do + +- **No cross-session or cross-user consolidation.** `Identity` is the + session ID; two sessions from the same human get two disjoint memory + scopes until the open identity-resolution decision in + `migration-decisions.md#5` is made. +- **No re-extraction guard, no deduplication.** A fact mentioned in two + overlapping passes may be written twice. `domain/memory.Query` + ranking/relevance is a read-side concern for whatever later consumes + these observations, not this curator's job to solve by inventing a + dedup index. +- **No `Forget`.** Nothing here decides a memory is stale; that is a + different, harder judgment call than "is this worth keeping," and nothing + currently reads these observations back into a chat turn to notice if + one turned out wrong. +- **No tool declarations.** `Manifest.Tools` is empty; the model call is + a plain completion (`ChatRequest.Tools` left nil), not agentic + tool-calling -- the extraction task does not need tools, and declaring + none is what keeps `Registrar.Tools` correctly absent from this + curator's view. +- **No feeding extracted observations back into the live system + prompt.** `internal/memory.Manager`'s existing frozen-snapshot + mechanism is untouched, same disclaimer as the memory-engine-contract + and builtin-engine issues before this one: the new `domain/memory` + path and the legacy live path run in parallel by design. Reading these + observations back into a chat turn is later, separate work. + +## Acceptance criteria + +Restated from the issue against this shape: + +1. Registers and runs through `curator.Registry` with no special-casing + -- the existing `Register`/`Runtime` path, no new registry method. +2. Writes through the memory engine contract, never a concrete store: + every write goes through `Registrar.MemoryEngines.Get(name).Write`, + resolved by name at call time exactly like the skill curator resolves + nothing store-specific either. +3. Extraction runs off the hot path: the model call happens inside + `Pass`, which the curator runtime already runs off a chat turn's own + goroutine (existing runtime guarantee, not something this issue + builds). +4. What it wrote and why is inspectable: one `Action` per session with a + count and the session ID, through the existing curator activity + tracker -- no new observability surface. +5. Honours the trigger-accounting invariant: `Manifest.OnInput = true` + wakes it on `events.KindTurnCompleted` via the existing + `WakeOnPrimaryInput` wiring, which already excludes every + curator-derived event kind from the forwarded set -- this curator's + own writes cannot reschedule it, with no new code needed for that + guarantee. + +## Files this change adds + +- `internal/domain/curator/registrar.go` -- `ConversationSource`, + `SessionSummary`, `ConversationMessage`, new `Conversations` field +- `internal/domain/curator/registry.go` -- `Conversations` gated like + `Skills` in `validateDeclared`/`filter` +- `internal/domain/curator/registry_test.go` -- table cases + fakes for + the new field, mirroring the existing `Skills`/`MemoryEngines` cases +- `internal/infrastructure/sessioncurator/adapter.go` -- wraps + `gateway.SessionStore` as `curator.ConversationSource` +- `internal/infrastructure/sessioncurator/adapter_test.go` +- `internal/infrastructure/sessioncurator/sessioncurator.go` -- the + `CuratorEngine` +- `internal/infrastructure/sessioncurator/sessioncurator_test.go` +- `internal/app/archied/bootstrap.go` -- register it in `setupCurators`, + wired to `b.chatSessionStore` and `b.cfg.BotUser` diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index 986916c6a..cc1ffe033 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -43,6 +43,7 @@ import ( "github.com/samcharles93/archie-core/internal/infrastructure/eventbus/nats" infraMemory "github.com/samcharles93/archie-core/internal/infrastructure/memory" "github.com/samcharles93/archie-core/internal/infrastructure/modelcatalog" + "github.com/samcharles93/archie-core/internal/infrastructure/sessioncurator" "github.com/samcharles93/archie-core/internal/infrastructure/skillcurator" "github.com/samcharles93/archie-core/internal/logging" "github.com/samcharles93/archie-core/internal/memory" @@ -847,10 +848,22 @@ func (b *boot) setupCurators(ctx context.Context) { // registry.filter narrows it out of the view for any curator that // doesn't declare Manifest.Skills, per curator not per instance. Skills: skillcurator.NewStore(skillsRoot), + // Conversations backs the session-memory curator; b.chatSessionStore + // is set by setupLLMAndChat, which Run() calls before setupCurators. + Conversations: sessioncurator.NewAdapter(b.chatSessionStore, b.cfg.BotUser), + LLM: curatorLLMRunner{rt: b.llm}, + // b.chatModels.ActiveModel() is the same source sendChatTurn uses + // for a real chat turn (telegram_setup.go) -- not + // b.defaultChatIdentity, which names a task-routing identity, not + // a model reference. + Model: b.chatModels.ActiveModel(), }) if err := b.curatorRegistry.Register(skillcurator.New(skillcurator.DefaultInterval)); err != nil { log.Error("skill curator registration failed", "err", err) } + if err := b.curatorRegistry.Register(sessioncurator.New(sessioncurator.DefaultInterval, infraMemory.EngineName)); err != nil { + log.Error("session-memory curator registration failed", "err", err) + } // The runtime owns the per-curator loops (archie-core-89x): one // goroutine per curator, wake nudges, per-pass budgets, panic // recovery, bounded shutdown. Stop order at shutdown: runtime first diff --git a/internal/app/archied/main.go b/internal/app/archied/main.go index ebcd2f174..fe6d63c4a 100644 --- a/internal/app/archied/main.go +++ b/internal/app/archied/main.go @@ -28,11 +28,13 @@ import ( natsio "github.com/nats-io/nats.go" "github.com/samcharles93/ai-sdk/chat" "github.com/samcharles93/ai-sdk/core" + "github.com/samcharles93/ai-sdk/runtime" "github.com/samcharles93/archie-core/internal/agentexec" "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/container" "github.com/samcharles93/archie-core/internal/daemon" + "github.com/samcharles93/archie-core/internal/domain/curator" "github.com/samcharles93/archie-core/internal/events" "github.com/samcharles93/archie-core/internal/forge" "github.com/samcharles93/archie-core/internal/forgerpc" @@ -462,6 +464,26 @@ func (s curatorEventSink) Emit(kind, detail string, data map[string]any) { s.b.Publish(events.Event{Kind: kind, Detail: detail, Data: data}) } +// curatorLLMRunner adapts the shared ai-sdk runtime to the curator +// family's narrow LLMRunner contract: one model reference, plain +// messages, no tools, no streaming -- curators that need more than a +// single completion are a bigger decision than this adapter makes. +type curatorLLMRunner struct { + rt *runtime.Runtime +} + +func (r curatorLLMRunner) Chat(ctx context.Context, req curator.ChatRequest) (curator.ChatResult, error) { + msgs := make([]chat.Message, 0, len(req.Messages)) + for _, m := range req.Messages { + msgs = append(msgs, chat.Message{Role: chat.Role(m.Role), Content: m.Content}) + } + res, err := r.rt.Chat(ctx, req.Model, core.GenerateOptions{Messages: msgs, MaxSteps: max(req.MaxSteps, 1)}) + if err != nil { + return curator.ChatResult{}, err + } + return curator.ChatResult{Text: res.Text}, nil +} + type chatTaskWriterAdapter struct { enqueue func( ctx context.Context, diff --git a/internal/domain/curator/contract.go b/internal/domain/curator/contract.go index aa211d04d..0668a12f1 100644 --- a/internal/domain/curator/contract.go +++ b/internal/domain/curator/contract.go @@ -61,6 +61,10 @@ type Manifest struct { // use memory; a memory operation without a declared engine is // rejected. MemoryEngine string + // Conversations declares the conversation-history capability + // (session-memory curator, archie-core-1786637499114). The registrar + // must carry a ConversationSource for a curator that declares it. + Conversations bool // Model is the model reference ("provider/model") passes use. Empty // uses the registrar's default. Model string diff --git a/internal/domain/curator/registrar.go b/internal/domain/curator/registrar.go index 9016e177e..893ad15c2 100644 --- a/internal/domain/curator/registrar.go +++ b/internal/domain/curator/registrar.go @@ -37,6 +37,10 @@ type Registrar struct { // trusted to pass its own declared identifier, not handed a // pre-scoped instance. MemoryEngines MemoryEngineSource + // Conversations is read-only recent conversation history, for a + // curator that declared Manifest.Conversations (session-memory + // curator, archie-core-1786637499114). Bound only when declared. + Conversations ConversationSource // Events publishes curator activity. Implementations must be // non-blocking and bounded (drop on overflow), so a curator can never // apply backpressure to a chat turn or the daemon. Always bound. @@ -109,6 +113,32 @@ type MemoryEngineSource interface { Get(name string) (domainmemory.MemoryEngine, bool) } +// ConversationSource is read-only conversation history, narrowed to what +// a curator needs to review recent activity -- never the full session +// CRUD/branch/search surface a chat gateway exposes. The app layer adapts +// the real session store to this. +type ConversationSource interface { + // RecentSessions returns every session touched at or after since, + // newest first. + RecentSessions(ctx context.Context, since time.Time) ([]SessionSummary, error) + // Messages returns the most recent n messages of one session, in + // chronological order. + Messages(ctx context.Context, sessionID string, n int) ([]ConversationMessage, error) +} + +// SessionSummary identifies one session and when it was last active. +type SessionSummary struct { + ID string + LastActive time.Time +} + +// ConversationMessage is one message in a session's history. +type ConversationMessage struct { + Role string // "user" or "assistant" + Content string + At time.Time +} + // EventSink publishes curator activity (what ran, what changed, why). It is // the emission side only; wake signals arrive through the runtime's own // subscription. Implementations MUST be non-blocking and diff --git a/internal/domain/curator/registry.go b/internal/domain/curator/registry.go index 4c3821a19..b95c3e26b 100644 --- a/internal/domain/curator/registry.go +++ b/internal/domain/curator/registry.go @@ -128,6 +128,9 @@ func (r *Registry) validateDeclared(m Manifest) error { if m.MemoryEngine != "" && r.host.MemoryEngines == nil { return errors.New("curator manifest: declares a memory engine but the registrar has no MemoryEngineSource") } + if m.Conversations && r.host.Conversations == nil { + return errors.New("curator manifest: declares conversation history but the registrar has no ConversationSource") + } return nil } @@ -149,11 +152,14 @@ func (r *Registry) filter(m Manifest) Registrar { if m.MemoryEngine == "" { v.MemoryEngines = nil } + if !m.Conversations { + v.Conversations = nil + } return v } func agentic(m Manifest) bool { - return len(m.Tools) > 0 || m.Skills || m.MemoryEngine != "" + return len(m.Tools) > 0 || m.Skills || m.MemoryEngine != "" || m.Conversations } // bindSafely isolates a panicking Bind: a curator that panics while diff --git a/internal/domain/curator/registry_test.go b/internal/domain/curator/registry_test.go index 6d920d9cb..af43e7d17 100644 --- a/internal/domain/curator/registry_test.go +++ b/internal/domain/curator/registry_test.go @@ -74,6 +74,19 @@ func (fakeMemoryEngine) List(context.Context, string) ([]domainmemory.Record, er } func (fakeMemoryEngine) Forget(context.Context, string) error { return nil } +// testConversations is a fake ConversationSource with one session and no +// messages -- enough for the presence/absence tests, which never call +// its methods. +type testConversations struct{} + +func (testConversations) RecentSessions(context.Context, time.Time) ([]SessionSummary, error) { + return nil, nil +} + +func (testConversations) Messages(context.Context, string, int) ([]ConversationMessage, error) { + return nil, nil +} + type testSink struct { mu sync.Mutex kinds []string @@ -354,6 +367,17 @@ func TestRegistryDeclaredCapabilitiesRequireHostServices(t *testing.T) { host: Registrar{MemoryEngines: testMemoryEngines{}}, manifest: Manifest{Interval: time.Hour, MemoryEngine: "builtin"}, }, + { + name: "conversations declared, no source", + host: Registrar{}, + manifest: Manifest{Interval: time.Hour, Conversations: true}, + wantErr: true, + }, + { + name: "conversations declared, source present", + host: Registrar{Conversations: testConversations{}}, + manifest: Manifest{Interval: time.Hour, Conversations: true}, + }, { name: "nothing declared, empty host", host: Registrar{}, @@ -382,6 +406,7 @@ func TestRegistryBindFiltersToDeclaredCapabilities(t *testing.T) { Tools: &testBuilder{}, Skills: testStore{}, MemoryEngines: testMemoryEngines{}, + Conversations: testConversations{}, Events: &testSink{}, Clock: testClock{now: time.Unix(0, 0)}, } @@ -405,6 +430,9 @@ func TestRegistryBindFiltersToDeclaredCapabilities(t *testing.T) { if plain.view.MemoryEngines != nil { t.Error("view.MemoryEngines = non-nil for a curator declaring no memory engine") } + if plain.view.Conversations != nil { + t.Error("view.Conversations = non-nil for a curator declaring no conversation history") + } if plain.view.Events == nil { t.Error("view.Events = nil; activity must always be attributable") } @@ -446,6 +474,19 @@ func TestRegistryBindFiltersToDeclaredCapabilities(t *testing.T) { if _, ok := mem.view.MemoryEngines.Get("builtin"); !ok { t.Error("view.MemoryEngines.Get(builtin) = not found, want the fake engine registered under that name") } + + // A curator declaring conversation history receives it, and model + // access to reason over it. + convo := newFake("convo", Manifest{Interval: time.Hour, Conversations: true}) + if err := r.Register(convo); err != nil { + t.Fatalf("Register(convo) = %v, want nil", err) + } + if convo.view.LLM == nil { + t.Error("view.LLM = nil for a curator declaring conversation history") + } + if convo.view.Conversations == nil { + t.Error("view.Conversations = nil for a curator declaring conversation history") + } } func TestRegistryBindPanicIsolated(t *testing.T) { diff --git a/internal/infrastructure/sessioncurator/adapter.go b/internal/infrastructure/sessioncurator/adapter.go new file mode 100644 index 000000000..dc7869544 --- /dev/null +++ b/internal/infrastructure/sessioncurator/adapter.go @@ -0,0 +1,63 @@ +// Package sessioncurator implements domain/curator.CuratorEngine for +// session memory extraction. See docs/prds/session-memory-curator.md for +// what a pass does and why, and the scope this package deliberately does +// not cover. +package sessioncurator + +import ( + "context" + "fmt" + "time" + + "github.com/samcharles93/archie-core/internal/domain/curator" + "github.com/samcharles93/archie-core/internal/gateway" +) + +// Adapter implements curator.ConversationSource over a real +// gateway.SessionStore, narrowed to the two read-only operations a +// curator needs -- never the full session CRUD/branch/search surface a +// chat gateway exposes. See docs/prds/session-memory-curator.md. +type Adapter struct { + store gateway.SessionStore + botUser string +} + +// NewAdapter builds an Adapter. botUser is compared against +// gateway.Message.From to derive role ("assistant" when it matches, else +// "user"), the same derivation gateway.compressTurnHistory already uses +// -- copied logic, not shared code, since curator must not import +// gateway.Message. +func NewAdapter(store gateway.SessionStore, botUser string) *Adapter { + return &Adapter{store: store, botUser: botUser} +} + +func (a *Adapter) RecentSessions(ctx context.Context, since time.Time) ([]curator.SessionSummary, error) { + sessions, err := a.store.List(ctx) + if err != nil { + return nil, fmt.Errorf("sessioncurator: listing sessions: %w", err) + } + var out []curator.SessionSummary + for _, s := range sessions { + if s.LastActiveAt.Before(since) { + continue + } + out = append(out, curator.SessionSummary{ID: s.SessionID, LastActive: s.LastActiveAt}) + } + return out, nil +} + +func (a *Adapter) Messages(ctx context.Context, sessionID string, n int) ([]curator.ConversationMessage, error) { + msgs, err := a.store.RecentMessages(ctx, sessionID, n) + if err != nil { + return nil, fmt.Errorf("sessioncurator: reading session %s: %w", sessionID, err) + } + out := make([]curator.ConversationMessage, 0, len(msgs)) + for _, m := range msgs { + role := "user" + if m.From == a.botUser { + role = "assistant" + } + out = append(out, curator.ConversationMessage{Role: role, Content: m.Text, At: m.At}) + } + return out, nil +} diff --git a/internal/infrastructure/sessioncurator/adapter_test.go b/internal/infrastructure/sessioncurator/adapter_test.go new file mode 100644 index 000000000..5e9db4366 --- /dev/null +++ b/internal/infrastructure/sessioncurator/adapter_test.go @@ -0,0 +1,72 @@ +package sessioncurator + +import ( + "context" + "testing" + "time" + + "github.com/samcharles93/archie-core/internal/gateway" +) + +func newTestStore(t *testing.T) gateway.SessionStore { + t.Helper() + s := gateway.NewSessionStoreMemory() + t.Cleanup(func() { _ = s.Close() }) + return s +} + +func TestAdapterRecentSessionsFiltersByActivity(t *testing.T) { + t.Parallel() + store := newTestStore(t) + ctx := context.Background() + + old := gateway.SessionContext{SessionID: "old", LastActiveAt: time.Unix(100, 0)} + recent := gateway.SessionContext{SessionID: "recent", LastActiveAt: time.Unix(2000, 0)} + if err := store.Save(ctx, old); err != nil { + t.Fatalf("Save(old) = %v", err) + } + if err := store.Save(ctx, recent); err != nil { + t.Fatalf("Save(recent) = %v", err) + } + + a := NewAdapter(store, "archie") + got, err := a.RecentSessions(ctx, time.Unix(1000, 0)) + if err != nil { + t.Fatalf("RecentSessions() = %v, want nil", err) + } + if len(got) != 1 || got[0].ID != "recent" { + t.Fatalf("RecentSessions() = %v, want only 'recent'", got) + } +} + +func TestAdapterMessagesDerivesRoleFromBotUser(t *testing.T) { + t.Parallel() + store := newTestStore(t) + ctx := context.Background() + + sess := gateway.SessionContext{SessionID: "s1", LastActiveAt: time.Unix(1000, 0)} + if err := store.Save(ctx, sess); err != nil { + t.Fatalf("Save() = %v", err) + } + if err := store.SaveMessage(ctx, "s1", gateway.Message{From: "user123", Text: "hello", At: time.Unix(1, 0)}); err != nil { + t.Fatalf("SaveMessage(user) = %v", err) + } + if err := store.SaveMessage(ctx, "s1", gateway.Message{From: "archie", Text: "hi there", At: time.Unix(2, 0)}); err != nil { + t.Fatalf("SaveMessage(bot) = %v", err) + } + + a := NewAdapter(store, "archie") + got, err := a.Messages(ctx, "s1", 10) + if err != nil { + t.Fatalf("Messages() = %v, want nil", err) + } + if len(got) != 2 { + t.Fatalf("Messages() = %v, want 2", got) + } + if got[0].Role != "user" || got[0].Content != "hello" { + t.Errorf("Messages()[0] = %+v, want user/hello", got[0]) + } + if got[1].Role != "assistant" || got[1].Content != "hi there" { + t.Errorf("Messages()[1] = %+v, want assistant/hi there", got[1]) + } +} diff --git a/internal/infrastructure/sessioncurator/sessioncurator.go b/internal/infrastructure/sessioncurator/sessioncurator.go new file mode 100644 index 000000000..60e11d7cf --- /dev/null +++ b/internal/infrastructure/sessioncurator/sessioncurator.go @@ -0,0 +1,213 @@ +package sessioncurator + +import ( + "context" + "encoding/json" + "fmt" + "strings" + "time" + + "github.com/samcharles93/archie-core/internal/domain/curator" + domainmemory "github.com/samcharles93/archie-core/internal/domain/memory" +) + +// Name is the identifier this curator registers under. +const Name = "session-memory" + +// ActionExtracted records a session's extracted observations being +// written. +const ActionExtracted = "memory.extracted" + +// DefaultInterval is the check-in cadence used when nothing more +// specific configures one, matching skillcurator.DefaultInterval's +// convention (no per-curator interval config surface exists yet). +const DefaultInterval = time.Hour + +const ( + // messageTailSize bounds how much of a session's history one pass + // reads, deliberately generous against the model's context rather + // than tuned tightly. See docs/prds/session-memory-curator.md. + messageTailSize = 40 + // maxObservationsPerSession caps how many facts one pass writes for + // one session -- a prompt-precision problem to fix, not a limit to + // quietly lift. + maxObservationsPerSession = 5 + // defaultLookback is what an unset PassInput.Since resolves to (the + // first pass, or the runtime declining to name a horizon). + defaultLookback = 24 * time.Hour +) + +// Curator implements domain/curator.CuratorEngine. See +// docs/prds/session-memory-curator.md for what a pass does and why: +// session-scoped extraction only, written through the bound memory +// engine, no cross-session consolidation, no forgetting. +type Curator struct { + interval time.Duration + engineName string + host curator.Registrar +} + +// New builds a session-memory curator that checks in every interval and +// writes through the named memory engine. +func New(interval time.Duration, engineName string) *Curator { + return &Curator{interval: interval, engineName: engineName} +} + +func (c *Curator) Name() string { return Name } +func (c *Curator) Version() string { return "1" } + +func (c *Curator) Manifest() curator.Manifest { + return curator.Manifest{ + Interval: c.interval, + OnInput: true, + Conversations: true, + MemoryEngine: c.engineName, + } +} + +func (c *Curator) Bind(host curator.Registrar) { c.host = host } + +func (c *Curator) Start(context.Context) error { return nil } + +func (c *Curator) Health(context.Context) curator.Health { + return curator.Health{Status: curator.HealthHealthy} +} + +func (c *Curator) Stop(context.Context) error { return nil } + +// Check reports whether any session has been active since the effective +// lookback horizon. Cheap: a session list, no model call. +func (c *Curator) Check(ctx context.Context) (bool, error) { + sessions, err := c.host.Conversations.RecentSessions(ctx, effectiveSince(time.Time{}, c.host.Clock.Now())) + if err != nil { + return false, err + } + return len(sessions) > 0, nil +} + +// Pass extracts durable observations from every session active since the +// last pass (or defaultLookback on the first pass) and writes them +// through the bound memory engine. See docs/prds/session-memory-curator.md +// for the exact extraction and classification rules. +func (c *Curator) Pass(ctx context.Context, in curator.PassInput) (curator.PassResult, error) { + engine, ok := c.host.MemoryEngines.Get(c.engineName) + if !ok { + return curator.PassResult{}, fmt.Errorf("sessioncurator: memory engine %q not found", c.engineName) + } + + since := effectiveSince(in.Since, c.host.Clock.Now()) + sessions, err := c.host.Conversations.RecentSessions(ctx, since) + if err != nil { + return curator.PassResult{}, err + } + + var actions []curator.Action + for _, sess := range sessions { + action, err := c.reviewOne(ctx, engine, sess.ID) + if err != nil { + return curator.PassResult{}, fmt.Errorf("session %q: %w", sess.ID, err) + } + if action != nil { + actions = append(actions, *action) + } + } + return curator.PassResult{Actions: actions}, nil +} + +// effectiveSince resolves a zero PassInput.Since to defaultLookback +// before now, rather than the beginning of time -- extracting from a +// session's entire history on the first pass is exactly the unbounded +// cold-start cost Check exists to keep cheap. +func effectiveSince(since, now time.Time) time.Time { + if since.IsZero() { + return now.Add(-defaultLookback) + } + return since +} + +// reviewOne extracts observations from one session's recent messages and +// writes them through engine. Returns nil (no Action) when nothing was +// extracted -- matching the skill curator's "a pass with nothing to +// report is not an error." +func (c *Curator) reviewOne(ctx context.Context, engine domainmemory.MemoryEngine, sessionID string) (*curator.Action, error) { + msgs, err := c.host.Conversations.Messages(ctx, sessionID, messageTailSize) + if err != nil { + return nil, err + } + if len(msgs) == 0 { + return nil, nil + } + + text, err := c.askModel(ctx, msgs) + if err != nil { + // A real model-call failure (provider down, timeout) is a Pass + // error: it says nothing about whether this session had anything + // worth extracting, unlike an unparseable response below. + return nil, err + } + facts, err := parseFacts(text) + if err != nil { + // A response that doesn't parse is "nothing extracted", not a + // pass failure -- the next pass tries again, and this is a + // curator, not a build gate. + return nil, nil //nolint:nilerr // documented above: a parse failure degrades to a no-op for this session, not a Pass error + } + if len(facts) == 0 { + return nil, nil + } + if len(facts) > maxObservationsPerSession { + facts = facts[:maxObservationsPerSession] + } + + for _, fact := range facts { + if _, err := engine.Write(ctx, domainmemory.Observation{ + Identity: sessionID, + Kind: "note", + Content: fact, + At: c.host.Clock.Now(), + }); err != nil { + return nil, err + } + } + + return &curator.Action{ + Type: ActionExtracted, + Detail: fmt.Sprintf("%s: wrote %d observation(s)", sessionID, len(facts)), + Reason: "session active since last pass", + }, nil +} + +// extractPrompt instructs the model to return a JSON array of short, +// durable strings -- facts, preferences, or corrections worth keeping -- +// or [] if nothing in the excerpt is worth keeping. No prose outside the +// array: the response is parsed directly as JSON. +const extractPrompt = `Review this conversation excerpt. List any durable facts, preferences, or corrections about the user or their work that are worth remembering for future conversations -- not the flow of the conversation itself, not anything already obvious from context, not one-off task details. + +Respond with ONLY a JSON array of short strings, one per fact. Respond with [] if nothing in this excerpt is worth keeping. No other text.` + +// askModel sends msgs plus the extraction instruction and returns the +// model's raw response text. A non-nil error here is a real failure +// (provider down, timeout) -- distinct from parseFacts failing on a +// response that came back but wasn't valid JSON. +func (c *Curator) askModel(ctx context.Context, msgs []curator.ConversationMessage) (string, error) { + chatMsgs := make([]curator.Message, 0, len(msgs)+1) + chatMsgs = append(chatMsgs, curator.Message{Role: "system", Content: extractPrompt}) + for _, m := range msgs { + chatMsgs = append(chatMsgs, curator.Message{Role: m.Role, Content: m.Content}) + } + + res, err := c.host.LLM.Chat(ctx, curator.ChatRequest{Model: c.host.Model, Messages: chatMsgs}) + if err != nil { + return "", err + } + return res.Text, nil +} + +// parseFacts parses the model's response as a JSON array of strings. +func parseFacts(text string) ([]string, error) { + var facts []string + if err := json.Unmarshal([]byte(strings.TrimSpace(text)), &facts); err != nil { + return nil, err + } + return facts, nil +} diff --git a/internal/infrastructure/sessioncurator/sessioncurator_test.go b/internal/infrastructure/sessioncurator/sessioncurator_test.go new file mode 100644 index 000000000..9fafe8425 --- /dev/null +++ b/internal/infrastructure/sessioncurator/sessioncurator_test.go @@ -0,0 +1,359 @@ +package sessioncurator + +import ( + "context" + "errors" + "testing" + "time" + + "github.com/samcharles93/archie-core/internal/domain/curator" + domainmemory "github.com/samcharles93/archie-core/internal/domain/memory" +) + +// --- fakes ------------------------------------------------------------- + +type fakeConversations struct { + sessions map[string]time.Time // id -> last active + messages map[string][]curator.ConversationMessage +} + +func (f *fakeConversations) RecentSessions(_ context.Context, since time.Time) ([]curator.SessionSummary, error) { + var out []curator.SessionSummary + for id, at := range f.sessions { + if at.Before(since) { + continue + } + out = append(out, curator.SessionSummary{ID: id, LastActive: at}) + } + return out, nil +} + +func (f *fakeConversations) Messages(_ context.Context, sessionID string, n int) ([]curator.ConversationMessage, error) { + msgs := f.messages[sessionID] + if len(msgs) > n { + msgs = msgs[len(msgs)-n:] + } + return msgs, nil +} + +// fakeLLM returns a canned response per call, or the same response every +// time if only one is configured. +type fakeLLM struct { + responses []string + err error + calls int +} + +func (f *fakeLLM) Chat(context.Context, curator.ChatRequest) (curator.ChatResult, error) { + if f.err != nil { + return curator.ChatResult{}, f.err + } + i := f.calls + f.calls++ + if i >= len(f.responses) { + i = len(f.responses) - 1 + } + return curator.ChatResult{Text: f.responses[i]}, nil +} + +type fakeEngine struct { + writes []domainmemory.Observation +} + +func (f *fakeEngine) Name() string { return "builtin" } +func (f *fakeEngine) Version() string { return "test" } +func (f *fakeEngine) Manifest() domainmemory.Manifest { return domainmemory.Manifest{} } +func (f *fakeEngine) Bind(domainmemory.Registrar) {} +func (f *fakeEngine) Start(context.Context) error { return nil } +func (f *fakeEngine) Health(context.Context) domainmemory.Health { + return domainmemory.Health{Status: domainmemory.HealthHealthy} +} +func (f *fakeEngine) Stop(context.Context) error { return nil } + +func (f *fakeEngine) Write(_ context.Context, obs domainmemory.Observation) (domainmemory.Record, error) { + f.writes = append(f.writes, obs) + return domainmemory.Record{ID: "id", Identity: obs.Identity, Content: obs.Content}, nil +} + +func (f *fakeEngine) Query(context.Context, domainmemory.Query) ([]domainmemory.Record, error) { + return nil, nil +} + +func (f *fakeEngine) List(context.Context, string) ([]domainmemory.Record, error) { return nil, nil } +func (f *fakeEngine) Forget(context.Context, string) error { return nil } + +type fakeEngineSource struct{ engine *fakeEngine } + +func (f fakeEngineSource) Get(name string) (domainmemory.MemoryEngine, bool) { + if name != "builtin" { + return nil, false + } + return f.engine, true +} + +type testClock struct{ now time.Time } + +func (c testClock) Now() time.Time { return c.now } +func (c testClock) After(d time.Duration) <-chan time.Time { return time.After(d) } + +func newTestCurator(t *testing.T, conv *fakeConversations, llm *fakeLLM, engine *fakeEngine) *Curator { + t.Helper() + c := New(time.Hour, "builtin") + c.Bind(curator.Registrar{ + Conversations: conv, + LLM: llm, + MemoryEngines: fakeEngineSource{engine: engine}, + Clock: testClock{now: time.Unix(1000, 0)}, + }) + return c +} + +// --- tests --------------------------------------------------------------- + +func TestCheckReportsFalseWithNoRecentSessions(t *testing.T) { + t.Parallel() + conv := &fakeConversations{sessions: map[string]time.Time{}} + c := newTestCurator(t, conv, &fakeLLM{}, &fakeEngine{}) + + ok, err := c.Check(context.Background()) + if err != nil { + t.Fatalf("Check() = %v, want nil", err) + } + if ok { + t.Error("Check() = true, want false: no recent sessions") + } +} + +func TestCheckReportsTrueWithARecentSession(t *testing.T) { + t.Parallel() + conv := &fakeConversations{sessions: map[string]time.Time{"s1": time.Unix(1000, 0)}} + c := newTestCurator(t, conv, &fakeLLM{}, &fakeEngine{}) + + ok, err := c.Check(context.Background()) + if err != nil { + t.Fatalf("Check() = %v, want nil", err) + } + if !ok { + t.Error("Check() = false, want true: a session is recently active") + } +} + +func TestPassExtractsAndWritesObservations(t *testing.T) { + t.Parallel() + conv := &fakeConversations{ + sessions: map[string]time.Time{"s1": time.Unix(1000, 0)}, + messages: map[string][]curator.ConversationMessage{ + "s1": {{Role: "user", Content: "I prefer tabs over spaces"}}, + }, + } + llm := &fakeLLM{responses: []string{`["prefers tabs over spaces"]`}} + engine := &fakeEngine{} + c := newTestCurator(t, conv, llm, engine) + + res, err := c.Pass(context.Background(), curator.PassInput{}) + if err != nil { + t.Fatalf("Pass() = %v, want nil", err) + } + if len(res.Actions) != 1 || res.Actions[0].Type != ActionExtracted { + t.Fatalf("Actions = %#v, want one %s", res.Actions, ActionExtracted) + } + if len(engine.writes) != 1 { + t.Fatalf("writes = %#v, want exactly 1", engine.writes) + } + got := engine.writes[0] + if got.Identity != "s1" { + t.Errorf("Identity = %q, want the session id, not a user/cross-session identity", got.Identity) + } + if got.Content != "prefers tabs over spaces" { + t.Errorf("Content = %q, want the extracted fact verbatim", got.Content) + } +} + +func TestPassTreatsUnparseableResponseAsNothingExtracted(t *testing.T) { + t.Parallel() + conv := &fakeConversations{ + sessions: map[string]time.Time{"s1": time.Unix(1000, 0)}, + messages: map[string][]curator.ConversationMessage{"s1": {{Role: "user", Content: "hello"}}}, + } + llm := &fakeLLM{responses: []string{"not json at all"}} + engine := &fakeEngine{} + c := newTestCurator(t, conv, llm, engine) + + res, err := c.Pass(context.Background(), curator.PassInput{}) + if err != nil { + t.Fatalf("Pass() = %v, want nil: an unparseable response is not a pass failure", err) + } + if len(res.Actions) != 0 { + t.Fatalf("Actions = %#v, want none", res.Actions) + } + if len(engine.writes) != 0 { + t.Fatalf("writes = %#v, want none", engine.writes) + } +} + +func TestPassEmptyArrayExtractsNothing(t *testing.T) { + t.Parallel() + conv := &fakeConversations{ + sessions: map[string]time.Time{"s1": time.Unix(1000, 0)}, + messages: map[string][]curator.ConversationMessage{"s1": {{Role: "user", Content: "hi"}}}, + } + llm := &fakeLLM{responses: []string{`[]`}} + engine := &fakeEngine{} + c := newTestCurator(t, conv, llm, engine) + + res, err := c.Pass(context.Background(), curator.PassInput{}) + if err != nil { + t.Fatalf("Pass() = %v, want nil", err) + } + if len(res.Actions) != 0 { + t.Fatalf("Actions = %#v, want none: nothing in the excerpt was worth keeping", res.Actions) + } +} + +func TestPassCapsObservationsPerSession(t *testing.T) { + t.Parallel() + conv := &fakeConversations{ + sessions: map[string]time.Time{"s1": time.Unix(1000, 0)}, + messages: map[string][]curator.ConversationMessage{"s1": {{Role: "user", Content: "lots of facts"}}}, + } + llm := &fakeLLM{responses: []string{`["a","b","c","d","e","f","g"]`}} + engine := &fakeEngine{} + c := newTestCurator(t, conv, llm, engine) + + if _, err := c.Pass(context.Background(), curator.PassInput{}); err != nil { + t.Fatalf("Pass() = %v, want nil", err) + } + if len(engine.writes) != maxObservationsPerSession { + t.Fatalf("writes = %d, want capped at %d", len(engine.writes), maxObservationsPerSession) + } +} + +func TestPassReviewsMultipleSessionsIndependently(t *testing.T) { + t.Parallel() + conv := &fakeConversations{ + sessions: map[string]time.Time{"s1": time.Unix(1000, 0), "s2": time.Unix(1000, 0)}, + messages: map[string][]curator.ConversationMessage{ + "s1": {{Role: "user", Content: "fact for s1"}}, + "s2": {{Role: "user", Content: "fact for s2"}}, + }, + } + llm := &fakeLLM{responses: []string{`["fact one"]`, `["fact two"]`}} + engine := &fakeEngine{} + c := newTestCurator(t, conv, llm, engine) + + res, err := c.Pass(context.Background(), curator.PassInput{}) + if err != nil { + t.Fatalf("Pass() = %v, want nil", err) + } + if len(res.Actions) != 2 { + t.Fatalf("Actions = %#v, want 2 (one per session)", res.Actions) + } + if len(engine.writes) != 2 { + t.Fatalf("writes = %#v, want 2", engine.writes) + } + identities := map[string]bool{} + for _, w := range engine.writes { + identities[w.Identity] = true + } + if !identities["s1"] || !identities["s2"] { + t.Errorf("writes scoped to identities %v, want both s1 and s2", identities) + } +} + +func TestPassUnknownEngineIsAnError(t *testing.T) { + t.Parallel() + c := New(time.Hour, "does-not-exist") + c.Bind(curator.Registrar{ + Conversations: &fakeConversations{}, + MemoryEngines: fakeEngineSource{engine: &fakeEngine{}}, + Clock: testClock{now: time.Unix(1000, 0)}, + }) + + if _, err := c.Pass(context.Background(), curator.PassInput{}); err == nil { + t.Fatal("Pass() with an unregistered engine name = nil, want error") + } +} + +func TestEffectiveSinceDefaultsToLookbackWindow(t *testing.T) { + t.Parallel() + now := time.Unix(1_000_000, 0) + got := effectiveSince(time.Time{}, now) + want := now.Add(-defaultLookback) + if !got.Equal(want) { + t.Errorf("effectiveSince(zero, now) = %v, want %v", got, want) + } +} + +func TestEffectiveSincePassesThroughAnExplicitValue(t *testing.T) { + t.Parallel() + explicit := time.Unix(500, 0) + got := effectiveSince(explicit, time.Unix(1_000_000, 0)) + if !got.Equal(explicit) { + t.Errorf("effectiveSince(explicit, now) = %v, want %v unchanged", got, explicit) + } +} + +func TestManifestShape(t *testing.T) { + t.Parallel() + c := New(15*time.Minute, "builtin") + m := c.Manifest() + if !m.OnInput { + t.Error("Manifest().OnInput = false, want true: wakes on completed chat turns") + } + if !m.Conversations { + t.Error("Manifest().Conversations = false, want true") + } + if m.MemoryEngine != "builtin" { + t.Errorf("Manifest().MemoryEngine = %q, want %q", m.MemoryEngine, "builtin") + } + if len(m.Tools) != 0 { + t.Errorf("Manifest().Tools = %v, want none: extraction is a plain completion, not tool-calling", m.Tools) + } + if !m.Skills { + // deliberately NOT checking true -- documents the negative + } + if m.Skills { + t.Error("Manifest().Skills = true, want false") + } +} + +func TestRegistersAndRunsThroughTheRegistry(t *testing.T) { + t.Parallel() + r := curator.NewRegistry(curator.Registrar{ + Conversations: &fakeConversations{}, + LLM: &fakeLLM{}, + MemoryEngines: fakeEngineSource{engine: &fakeEngine{}}, + }) + c := New(time.Hour, "builtin") + if err := r.Register(c); err != nil { + t.Fatalf("Register() = %v, want nil", err) + } + if err := r.Start(context.Background()); err != nil { + t.Fatalf("registry Start() = %v, want nil", err) + } + if health := r.Health(context.Background()); health[Name].Status != curator.HealthHealthy { + t.Errorf("Health() = %v, want healthy", health) + } + if err := r.Stop(context.Background()); err != nil { + t.Fatalf("registry Stop() = %v, want nil", err) + } +} + +var errLLM = errors.New("model unavailable") + +func TestPassPropagatesALLMFailure(t *testing.T) { + // Unlike an unparseable response, the model call itself failing (the + // provider is down) is a real Pass error, not a "nothing to extract" + // outcome. + t.Parallel() + conv := &fakeConversations{ + sessions: map[string]time.Time{"s1": time.Unix(1000, 0)}, + messages: map[string][]curator.ConversationMessage{"s1": {{Role: "user", Content: "hi"}}}, + } + llm := &fakeLLM{err: errLLM} + c := newTestCurator(t, conv, llm, &fakeEngine{}) + + if _, err := c.Pass(context.Background(), curator.PassInput{}); !errors.Is(err, errLLM) { + t.Fatalf("Pass() error = %v, want it to wrap the LLM failure", err) + } +}