Includes MCP crash-after-init test fix (crash moved from handle() to serve() entry point so transport sees immediate subprocess death).
95 lines
4.3 KiB
Go
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
|
|
}
|