Files
archie/internal/memory/builtin/provider.go
T
sam 739d4530de refactor(memory): delete the unreachable <memory> fence scrubber
internal/memory/scrubber had no importer anywhere in the repo; the
only emitter of <memory> fences (builtin.Provider.SystemPromptBlock)
also has no caller in the streaming output path, so the whole package
was dead code. Deleted it and the doc comment claiming a scrubber
consumes SystemPromptBlock's output.
2026-09-15 10:18:29 +10:00

404 lines
14 KiB
Go

package builtin
import (
"fmt"
"os"
"path/filepath"
"strings"
"sync"
"github.com/samcharles93/archie-core/internal/memory"
"github.com/samcharles93/archie-core/internal/tools"
)
// providerName is the value returned by Provider.Name() and used to route
// tool calls to this provider.
const providerName = "builtin"
// toolName is the single tool this provider exposes to the agent.
const toolName = "memory_edit"
// Config configures a Provider.
type Config struct {
// Dir is the directory MEMORY.md and USER.md are read from and written
// to (e.g. ~/.config/archie/profiles/{profile}/memory/). It is created
// if it does not exist.
Dir string
// MaxFileBytes bounds the size of each file. Zero or negative uses
// defaultMaxFileBytes (100KB).
MaxFileBytes int
// DisableFrozenSnapshot, when true, causes SystemPromptBlock() to read
// live content from the stores on every call instead of using the
// snapshot captured at Initialize() time. Defaults to false (frozen
// snapshot enabled).
DisableFrozenSnapshot bool
}
// Provider is the built-in, file-backed MemoryProvider. It persists agent
// memory to MEMORY.md and user-provided context to USER.md under Config.Dir,
// and exposes a single "memory_edit" tool with add/replace/remove actions.
//
// By default, the provider captures a frozen snapshot of both files at
// Initialize() time and uses that snapshot for the system prompt block
// (SystemPromptProvider). Writes go to disk immediately but the snapshot is
// not updated mid-session -- only the next session (or next Initialize call)
// picks up the changes. Set Config.FrozenSnapshot to false to read live
// content on every SystemPromptBlock() call.
type Provider struct {
memory *Store
user *Store
// frozenSnapshotEnabled mirrors Config.FrozenSnapshot. When unset
// (default), Initialize() captures a snapshot that SystemPromptBlock()
// returns for the lifetime of the session.
frozenSnapshotEnabled bool
// frozenMu guards frozenMemory and frozenUser, since Initialize() can
// race with SystemPromptBlock() if a caller re-initializes a session on
// a Provider shared across goroutines.
frozenMu sync.RWMutex
// frozen memory and frozen user hold the Render() output captured at
// Initialize() time. They are only valid after Initialize() has been
// called and only used when frozenSnapshotEnabled is true.
frozenMemory string
frozenUser string
// dirErr records a Config.Dir that could not be established. The
// provider stays usable for reads -- a memory that cannot be written is
// still better than a daemon that will not start -- and reports itself
// unavailable so the failure is visible rather than looking like a
// memory that simply has nothing in it yet.
dirErr error
}
// New creates a Provider backed by the two markdown files under cfg.Dir.
// Both files are read immediately so the provider is ready for use as soon
// as New returns.
//
// An unusable cfg.Dir is reported through IsAvailable and Err, not by
// failing: memory is one capability among many, and a bad path is not worth
// refusing to start over. The caller decides whether to fall back elsewhere.
// Establishing the directory here is still what makes the problem visible at
// all -- both stores treat a missing file as an empty document, so otherwise
// a directory that does not exist is indistinguishable from a memory that
// simply has nothing in it yet, and the failure surfaces at the agent's
// first write, mid-conversation.
//
// FrozenSnapshot defaults to true (frozen snapshot enabled). Set it
// explicitly to false to have SystemPromptBlock() read live content from
// the stores.
func New(cfg Config) (*Provider, error) {
if cfg.Dir == "" {
return nil, fmt.Errorf("builtin: Config.Dir must not be empty")
}
var dirErr error
if err := os.MkdirAll(cfg.Dir, 0o755); err != nil {
dirErr = fmt.Errorf("builtin: memory directory %s unusable: %w", cfg.Dir, err)
}
// A store that cannot read its file starts empty rather than failing,
// for the same reason: reads must keep working on a degraded provider.
memStore, err := NewStore(filepath.Join(cfg.Dir, "MEMORY.md"), cfg.MaxFileBytes)
if err != nil {
if dirErr == nil {
dirErr = err
}
memStore = emptyStore(filepath.Join(cfg.Dir, "MEMORY.md"), cfg.MaxFileBytes)
}
userStore, err := NewStore(filepath.Join(cfg.Dir, "USER.md"), cfg.MaxFileBytes)
if err != nil {
if dirErr == nil {
dirErr = err
}
userStore = emptyStore(filepath.Join(cfg.Dir, "USER.md"), cfg.MaxFileBytes)
}
// Frozen snapshot is enabled by default (DisableFrozenSnapshot defaults
// to false).
frozen := !cfg.DisableFrozenSnapshot
return &Provider{
memory: memStore,
user: userStore,
frozenSnapshotEnabled: frozen,
dirErr: dirErr,
}, nil
}
// Name returns the provider's identifier.
func (p *Provider) Name() string { return providerName }
// IsAvailable reports whether the backing directory could be established.
// The built-in provider has one external dependency after all -- the
// filesystem -- and a directory it cannot write to means memory reads as
// empty and every write will fail.
func (p *Provider) IsAvailable() bool { return p.dirErr == nil }
// Err returns why the provider is unavailable, or nil. Callers log this: an
// operator told only that memory is unavailable has nothing to act on.
func (p *Provider) Err() error { return p.dirErr }
// SystemPromptBlock implements memory.SystemPromptProvider. It returns a
// markdown-formatted block containing the frozen snapshot of MEMORY.md and
// USER.md content, wrapped in <memory>…</memory> fences.
//
// When the frozen snapshot is enabled (the default), the block is built from
// the snapshot captured at Initialize() time and does not change for the
// duration of the session. When disabled (Config.DisableFrozenSnapshot =
// true), the block is built from the live store content on every call.
//
// Returns an empty string when both stores are empty.
func (p *Provider) SystemPromptBlock() string {
mem, user := p.snapshotContent()
if mem == "" && user == "" {
return ""
}
var sb strings.Builder
sb.WriteString("<memory>\n")
if mem != "" {
sb.WriteString(mem)
}
if user != "" {
if mem != "" {
sb.WriteString("\n")
}
sb.WriteString(user)
}
sb.WriteString("\n</memory>\n")
return sb.String()
}
// snapshotContent returns the memory and user content, either from the frozen
// snapshot or live from the stores, depending on the FrozenSnapshot config.
func (p *Provider) snapshotContent() (memory, user string) {
if p.frozenSnapshotEnabled {
p.frozenMu.RLock()
defer p.frozenMu.RUnlock()
return p.frozenMemory, p.frozenUser
}
return p.memory.Render(), p.user.Render()
}
// Initialize reloads MEMORY.md and USER.md from disk so that any changes
// made outside this process (or by a previous provider instance) since
// New was called are picked up before the session begins.
//
// When frozen snapshot is enabled (the default), Initialize captures the
// rendered content of both files for use by SystemPromptBlock(). The snapshot
// is not updated on subsequent writes -- only the next Initialize() call (or
// the next session) picks up the fresh content.
func (p *Provider) Initialize(sessionID string) error {
if err := p.memory.Reload(); err != nil {
return err
}
if err := p.user.Reload(); err != nil {
return err
}
if p.frozenSnapshotEnabled {
mem := p.memory.Render()
user := p.user.Render()
p.frozenMu.Lock()
p.frozenMemory = mem
p.frozenUser = user
p.frozenMu.Unlock()
}
return nil
}
// GetToolSchemas returns the memory_edit tool definition. Handler is left
// nil so the MemoryManager injects a delegating handler via
// ToolCallProvider (see Manager.GetToolSchemas); callers that bypass the
// Manager should invoke HandleToolCall directly.
func (p *Provider) GetToolSchemas() []tools.ToolEntry {
return []tools.ToolEntry{
{
Name: toolName,
Toolset: "memory",
Description: "Persist or edit agent memory. Add, replace, or remove content in a named section of MEMORY.md (agent memory) or USER.md (user-provided context).",
Schema: toolSchema,
},
}
}
// toolSchema is the JSON Schema for the memory_edit tool's input.
var toolSchema = tools.JSONSchema{
"type": "object",
"properties": map[string]any{
"file": map[string]any{
"type": "string",
"enum": []string{"memory", "user"},
"description": "Which file to edit: \"memory\" for MEMORY.md (agent memory) or \"user\" for USER.md (user-provided context). Defaults to \"memory\".",
},
"action": map[string]any{
"type": "string",
"enum": []string{"add", "replace", "remove"},
"description": "The action to perform: add a new entry, replace a substring, or remove a matching entry.",
},
"section": map[string]any{
"type": "string",
"description": "Name of the section (markdown header) to operate on. Alphanumeric and spaces only, max 64 characters. Created automatically by \"add\" if it does not exist.",
},
"content": map[string]any{
"type": "string",
"description": "Content to append as a new entry. Required for the \"add\" action.",
},
"substring": map[string]any{
"type": "string",
"description": "Exact substring to locate within the section. Required for \"replace\" and \"remove\".",
},
"replacement": map[string]any{
"type": "string",
"description": "Text to substitute in place of substring. Required for the \"replace\" action.",
},
"case_sensitive": map[string]any{
"type": "boolean",
"description": "Whether substring matching is case-sensitive. Defaults to true.",
},
},
"required": []string{"action", "section"},
}
// HandleToolCall implements memory.ToolCallProvider. It dispatches the
// memory_edit tool's add/replace/remove actions to the selected store.
func (p *Provider) HandleToolCall(name string, args map[string]any) (any, error) {
if name != toolName {
return nil, fmt.Errorf("builtin: unknown tool %q", name)
}
store, fileLabel, err := p.selectStore(args)
if err != nil {
return nil, err
}
action, _ := args["action"].(string)
caseSensitive := true
if v, ok := args["case_sensitive"].(bool); ok {
caseSensitive = v
}
switch action {
case "add":
return p.handleAdd(store, fileLabel, args)
case "replace":
return p.handleReplace(store, fileLabel, args, caseSensitive)
case "remove":
return p.handleRemove(store, fileLabel, args, caseSensitive)
default:
return nil, fmt.Errorf("builtin: unknown action %q (want add, replace, or remove)", action)
}
}
func (p *Provider) handleAdd(store *Store, fileLabel string, args map[string]any) (any, error) {
content, _ := args["content"].(string)
if content == "" {
return nil, fmt.Errorf("builtin: add requires non-empty \"content\"")
}
section, _ := args["section"].(string)
res, err := store.Add(section, content)
if err != nil {
return nil, err
}
verb := "appended to"
if res.Created {
verb = "created"
}
return map[string]any{
"success": true,
"file": fileLabel,
"action": "add",
"section": res.Section,
"chars_added": res.CharsAdded,
"section_chars": res.SectionChars,
"file_bytes": res.FileBytes,
"message": fmt.Sprintf("%s section %q (%d chars added, %d bytes in file)", capitalize(verb), res.Section, res.CharsAdded, res.FileBytes),
}, nil
}
func (p *Provider) handleReplace(store *Store, fileLabel string, args map[string]any, caseSensitive bool) (any, error) {
substring, _ := args["substring"].(string)
replacement, _ := args["replacement"].(string)
if substring == "" {
return nil, fmt.Errorf("builtin: replace requires non-empty \"substring\"")
}
section, _ := args["section"].(string)
res, err := store.Replace(section, substring, replacement, caseSensitive)
if err != nil {
return nil, err
}
return map[string]any{
"success": true,
"file": fileLabel,
"action": "replace",
"section": res.Section,
"chars_removed": res.CharsRemoved,
"chars_added": res.CharsAdded,
"section_chars": res.SectionChars,
"file_bytes": res.FileBytes,
"message": fmt.Sprintf("Replaced %d chars with %d chars in section %q (%d bytes in file)", res.CharsRemoved, res.CharsAdded, res.Section, res.FileBytes),
}, nil
}
func (p *Provider) handleRemove(store *Store, fileLabel string, args map[string]any, caseSensitive bool) (any, error) {
substring, _ := args["substring"].(string)
if substring == "" {
return nil, fmt.Errorf("builtin: remove requires non-empty \"substring\"")
}
section, _ := args["section"].(string)
res, err := store.Remove(section, substring, caseSensitive)
if err != nil {
return nil, err
}
return map[string]any{
"success": true,
"file": fileLabel,
"action": "remove",
"section": res.Section,
"chars_removed": res.CharsRemoved,
"section_chars": res.SectionChars,
"file_bytes": res.FileBytes,
"message": fmt.Sprintf("Removed %d chars from section %q (%d bytes in file)", res.CharsRemoved, res.Section, res.FileBytes),
}, nil
}
// selectStore resolves the "file" argument to the corresponding store,
// defaulting to the memory (MEMORY.md) store.
func (p *Provider) selectStore(args map[string]any) (*Store, string, error) {
file, _ := args["file"].(string)
switch file {
case "", "memory":
return p.memory, "memory", nil
case "user":
return p.user, "user", nil
default:
return nil, "", fmt.Errorf("builtin: unknown file %q (want \"memory\" or \"user\")", file)
}
}
// capitalize upper-cases the first byte of s. It is only used for
// short, ASCII, English status verbs, so byte-level capitalization is
// sufficient.
func capitalize(s string) string {
if s == "" {
return s
}
b := []byte(s)
if b[0] >= 'a' && b[0] <= 'z' {
b[0] -= 'a' - 'A'
}
return string(b)
}
// Compile-time interface checks.
var (
_ memory.MemoryProvider = (*Provider)(nil)
_ memory.ToolCallProvider = (*Provider)(nil)
_ memory.SystemPromptProvider = (*Provider)(nil)
)