feat: OpenViking integration for persistent agent memory and context retrieval

[logosc]

Overview

Integrate with OpenViking to give mini-agent-go agents persistent cross-session memory and hierarchical context retrieval. OpenViking is a context database that organizes memories, resources, and skills into a virtual filesystem with tiered loading (L0 summary → L1 overview → L2 full content) and semantic search.

Why

mini-agent-go's biggest gap today is that Engine.Run loses all state when it returns. The current compactMessages does LLM-based summarization but is lossy and session-scoped. OpenViking solves this with:

• Structured memory extraction — categorizes memories (preferences, entities, events, patterns) instead of a flat summary
• Cross-session persistence — memories survive across sessions via a virtual filesystem backed by vector storage
• Hierarchical retrieval — agent can browse context at different detail levels rather than stuffing everything into the system prompt

Dependency: OpenViking Go SDK

OpenViking has a planned Go SDK (task T11 in their design doc) — a thin stdlib-only HTTP client wrapping their REST API. The SDK is not yet shipped but the API surface is defined:

client := openviking.NewClient(openviking.Config{
    URL:    "http://localhost:1933",
    APIKey: "your-api-key",
})

// Semantic search across memory/resources
results, _ := client.Find("user preferences for code style", &openviking.FindOptions{Limit: 5})

// Filesystem browsing (tiered context)
listing, _ := client.Ls("viking://user/memories/")       // L0 summaries
overview, _ := client.Overview("viking://user/memories/preferences")  // L1
content, _ := client.Read("viking://user/memories/preferences/code-style")  // L2 full

This issue is blocked until the Go SDK ships (or we implement a minimal client ourselves against the HTTP API).

Proposed integration

1. VikingSearchTool — agent-driven context retrieval

A Tool[S] that wraps client.Find(). The agent decides when it needs context and searches for it, rather than pre-loading everything.

// Usage in engine setup
engine.Tools = append(engine.Tools, NewVikingSearchTool(vikingClient))

2. VikingFSTool — tiered filesystem browsing

A Tool[S] that exposes ls, read, abstract, overview as sub-commands. The agent can browse the context tree at different detail levels (L0/L1/L2), matching mini-agent-go's existing LazyTools pattern of loading detail on demand.

3. VikingMemoryHook — automatic memory persistence

Hooks into the engine lifecycle to extract and persist memories:

• On session end: Extract structured memories from the conversation (replacing or augmenting compactMessages)
• On session start: Retrieve relevant context and inject into the system prompt or first user message

This requires a new OnSessionEnd hook on Engine[S] (or piggyback on an existing hook point).

4. Keep it optional

OpenViking integration must be opt-in. mini-agent-go should continue to work with zero dependencies when OpenViking isn't running. The integration should live in a separate package (e.g., viking/) or behind a build tag so it doesn't add imports to the core.

Non-goals

• Replacing mini-agent-go's compactMessages entirely — it still works as a fallback when OpenViking isn't available
• Embedding OpenViking as a library — always connect via HTTP client to a running server
• Implementing the full Go SDK ourselves — wait for upstream or contribute to their repo

References

• OpenViking repo
• Go SDK design spec (T11)
• Server/client design doc
• API overview