Documentation
¶
Overview ¶
Package memory manages the engine's local copy of an agent's declared memory files. The local filesystem is the source of truth: the manager owns a directory of <uid>.json records, reads them at boot, and writes through to disk on every successful mutation. An optional remote mirror (engine.MemorySync) hydrates an empty local copy on a cold start and receives a best-effort push after each local write; with no mirror the manager is fully functional offline.
Index ¶
- Variables
- func IndexCard(refs []workflow.MemoryRef, mgr *Manager) (string, error)
- func Tools(refs []workflow.MemoryRef, mgr *Manager) ([]llmproxy.Tool, error)
- func ValidateRefs(refs []workflow.MemoryRef, mgr *Manager) error
- type Card
- type Manager
- func (m *Manager) Append(ctx context.Context, uid, content string) error
- func (m *Manager) Card(uid string) (Card, error)
- func (m *Manager) Edit(ctx context.Context, uid, oldStr, newStr string) error
- func (m *Manager) Read(uid string) (string, error)
- func (m *Manager) Restore(ctx context.Context, declared []workflow.MemoryFile) error
- func (m *Manager) UIDs() []string
Constants ¶
This section is empty.
Variables ¶
var ErrEditNoMatch = errors.New("memory edit: old_string not found in file")
ErrEditNoMatch is returned by Edit when the supplied old_string isn't present in the file. The LLM is expected to recover by re-reading.
var ErrFileNotFound = errors.New("memory file not found")
ErrFileNotFound is returned when the LLM references a memory file that isn't declared for this agent.
var ErrSizeExceeded = errors.New("memory write would exceed max size")
ErrSizeExceeded is returned when an append/edit would push the file past its declared maxSizeBytes cap.
Functions ¶
func IndexCard ¶
IndexCard renders the auto-injected memory index block prepended to the LLM agent's system prompt. One line per file with name, mode, size, and description so the LLM can decide what to fetch.
func Tools ¶
Tools synthesizes the LLM-callable tools (read_memory, append_memory, edit_memory) for the given memory refs. Each tool's `file` parameter is constrained by enum to the human names of files this agent is allowed to touch (read-only refs excluded from write enums). Internally, each tool resolves the chosen name to its uid before calling the manager.
Returns nil when refs is empty.
Types ¶
type Card ¶
Card is the metadata used to render an entry in the auto-injected memory index in the LLM agent's system prompt. Size is in bytes; the LLM treats it as a hint, not a hard contract.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager is the engine-side memory subsystem. One instance per engine process. Files are keyed internally by uid (stable across renames); the LLM-facing tool layer resolves human names to uids via Card.
func NewManager ¶
func NewManager(dir string, sync engine.MemorySync) *Manager
NewManager constructs a manager whose durable copy lives in dir. sync is the optional remote mirror; pass nil for local-only operation. The directory is created lazily on Restore.
func (*Manager) Append ¶
Append concatenates content to the file identified by uid, persists it locally, and mirrors the new full content best-effort. Returns ErrSizeExceeded if the result would exceed the declared cap.
func (*Manager) Card ¶
Card returns the metadata for the file identified by uid. Tool builders use this to translate refs into LLM-facing enums and index cards.
func (*Manager) Edit ¶
Edit performs a single find/replace against the file identified by uid. Returns ErrEditNoMatch if oldStr isn't present. First match only, matching Claude Code's Edit semantics.
func (*Manager) Restore ¶
Restore rebuilds the working copy for the files declared by the current deploy. Called from Builder.Build, so every deploy reconciles state (boot and post-rename redeploy). The local filesystem wins: for each declared file an existing local copy is kept as-is (preserving the agent's accumulated edits). Files with no local copy are seeded — from the remote mirror on a cold start (empty local dir, mirror configured), otherwise from the declared content carried in the workflow. Declared metadata (name, description, size cap) is always authoritative; only content is preserved across redeploys.
Source Files