Files
archie/internal/memory/provider.go
T
sam f6d51416f0 chore: replace 607 em-dashes with double hyphens project-wide
Includes MCP crash-after-init test fix (crash moved from handle() to serve()
entry point so transport sees immediate subprocess death).
2026-07-26 09:53:33 +10:00

95 lines
4.3 KiB
Go

// Package memory defines the pluggable memory provider architecture for
// archie-core. Providers implement the core MemoryProvider interface; optional
// behavior is exposed through sub-interfaces that the MemoryManager discovers
// at runtime via type assertion.
package memory
import "github.com/samcharles93/archie-core/internal/tools"
// MemoryProvider is the contract that every memory provider -- built-in or
// external/plugin -- must implement. It covers provider identity, availability,
// session-scoped initialization, and tool schema export.
type MemoryProvider interface {
// Name returns a unique, human-readable identifier for this provider
// (e.g. "sqlite", "filesystem", "chroma"). The name is used in
// configuration, logging, and tool-call routing.
Name() string
// IsAvailable reports whether the provider is ready for use. A provider
// may return false when a required binary is missing, a connection is
// down, or it has not been configured.
IsAvailable() bool
// Initialize prepares the provider for the given session. It is called
// once per session before any other methods. sessionID is the unique
// identifier assigned to the current agent session.
Initialize(sessionID string) error
// GetToolSchemas returns the tool definitions this provider exports to
// the agent at discovery time. The returned entries include both the
// JSON Schema (for LLM consumption) and the Handler (for execution).
// Return nil or an empty slice if the provider has no tools.
GetToolSchemas() []tools.ToolEntry
}
// ── Optional sub-interfaces (discovered via type assertion) ──────────────
// SystemPromptProvider is an optional interface that providers may implement
// to contribute a block of text to the system prompt. The block is injected
// at a well-known location so the agent understands what memory tools are
// available and how to use them.
type SystemPromptProvider interface {
// SystemPromptBlock returns a markdown-formatted block of instructions
// that is injected into the agent's system prompt.
SystemPromptBlock() string
}
// PrefetchProvider is an optional interface for providers that support
// anticipatory memory retrieval. When the agent is about to begin a turn,
// the MemoryManager calls Prefetch with the current user query so the
// provider can warm its caches or pre-load relevant context.
type PrefetchProvider interface {
// Prefetch retrieves memory relevant to the given query and returns it
// as a string suitable for injection into the agent's context. The
// returned string may be empty if no relevant memory is found.
Prefetch(query string) (string, error)
// QueuePrefetch enqueues a prefetch request for asynchronous execution.
// The provider schedules the lookup and the result is made available
// through the provider's normal retrieval path on a subsequent call.
QueuePrefetch(query string) error
}
// SyncTurnProvider is an optional interface for providers that persist
// conversation turns. After each assistant response, the MemoryManager
// calls SyncTurn so the provider can store the exchange for future
// retrieval.
type SyncTurnProvider interface {
// SyncTurn stores a single user/assistant exchange. userMsg is the
// content the user sent; assistantMsg is the content the assistant
// produced in response.
SyncTurn(userMsg, assistantMsg string) error
}
// ToolCallProvider is an optional interface for providers that handle
// tool calls directly. When the agent invokes a memory tool, the
// MemoryManager routes the call to the provider that owns the tool.
type ToolCallProvider interface {
// HandleToolCall executes the named tool with the given arguments.
// name identifies the tool (matching one of the entries returned by
// GetToolSchemas). args contains the deserialized input parameters.
// The return value is serialized to JSON and included in the tool
// result sent back to the agent.
HandleToolCall(name string, args map[string]any) (any, error)
}
// ShutdownProvider is an optional interface for providers that need to
// release resources, flush buffers, or close connections when the agent
// session ends.
type ShutdownProvider interface {
// Shutdown gracefully tears down the provider. It is called once when
// the MemoryManager itself is shutting down. The provider should release
// all resources and return any final error.
Shutdown() error
}