Documentation
¶
Overview ¶
Package memory defines long-term memory for agents: entry types, the Store interface every backend implements, the Governed wrapper that applies the write policy (taint gate, sanitizing, tombstones, budget, events) and the Router that dispatches scopes to backends.
The package only depends on the standard library and agentcore/redact so that hosts and backends (files, gofer, exec) can share it.
Index ¶
- Constants
- Variables
- func BackendName(s Store) string
- func CleanSummary(s string) string
- func Fingerprint(title, body string) string
- func FirstSentence(body string) string
- func Slug(title string) string
- func UniqueID(base string, taken func(id string) bool) string
- func ValidateID(id string) error
- type Action
- type Budget
- type BudgetError
- type Entry
- type Enumerator
- type Event
- type Governed
- func (g *Governed) BackendName() string
- func (g *Governed) Get(ctx context.Context, s Scope, id string) (Entry, error)
- func (g *Governed) Index(ctx context.Context, s Scope) (Index, error)
- func (g *Governed) Route(s Scope) (Store, error)
- func (g *Governed) Search(ctx context.Context, s Scope, q string, limit int) ([]Hit, error)
- func (g *Governed) Write(ctx context.Context, s Scope, op Op) (Entry, error)
- type Hit
- type Index
- type IndexLine
- type Kind
- type Named
- type Op
- type Policy
- type Provenance
- type ProvenanceStore
- type Resolver
- type RouteInfo
- type Router
- func (r *Router) Backends() []RouteInfo
- func (r *Router) Get(ctx context.Context, s Scope, id string) (Entry, error)
- func (r *Router) Index(ctx context.Context, s Scope) (Index, error)
- func (r *Router) Register(scopeKind string, s Store) error
- func (r *Router) Route(s Scope) (Store, error)
- func (r *Router) Search(ctx context.Context, s Scope, q string, limit int) ([]Hit, error)
- func (r *Router) Write(ctx context.Context, s Scope, op Op) (Entry, error)
- type Scope
- type Store
- type Summarizer
Constants ¶
const ( DefaultMaxLines = 200 DefaultMaxBytes = 16 * 1024 )
Default index budget per scope (design D6). Over-budget writes fail; the index is never truncated silently.
const ( EventWrite = "memory_write" EventDenied = "memory_denied" )
Event types passed to Policy.Observe.
const ( ReasonInvalid = "invalid" ReasonNeedsConfirmation = "needs_confirmation" ReasonDenied = "denied" ReasonTombstoned = "tombstoned" ReasonOverBudget = "over_budget" )
Deny reasons carried by memory_denied events.
const ( ScopeUser = "user" ScopeProject = "project" ScopePeople = "people" )
Scope kinds. people is reserved for a later phase; it parses but no backend is registered for it by default.
const MaxIDLen = 80
MaxIDLen bounds entry ids; slugs are cut shorter to leave room for suffixes.
const SummaryMaxRunes = 120
SummaryMaxRunes bounds a one-line summary; longer text is cut and ends with "…" so one entry can never flood the resident index.
Variables ¶
var ( // ErrInvalid marks malformed input: unknown kind/scope/action, bad id, // empty title or body. ErrInvalid = errors.New("memory: invalid request") // ErrNotFound marks a missing entry. ErrNotFound = errors.New("memory: entry not found") // ErrNeedsConfirmation: the session is tainted and the host offers no // way to confirm (Policy.Confirm is nil), so the write is refused. ErrNeedsConfirmation = errors.New("memory: write from a tainted session needs confirmation") // ErrDenied: the session is tainted and Confirm refused the write. ErrDenied = errors.New("memory: write denied") // ErrTombstoned: the content matches an entry that was removed before. ErrTombstoned = errors.New("memory: content matches a removed entry") // ErrOverBudget: the write would push the scope index over its budget. ErrOverBudget = errors.New("memory: index budget exceeded") // ErrNoBackend: no backend is registered for the scope. ErrNoBackend = errors.New("memory: no backend for scope") )
Errors returned by this package; test them with errors.Is.
Functions ¶
func BackendName ¶
BackendName returns s's Named name, or "unknown".
func CleanSummary ¶
CleanSummary folds s onto one line (runs of whitespace become one space) and truncates it to SummaryMaxRunes runes.
func Fingerprint ¶
Fingerprint identifies entry content for tombstones: sha256 over the lowercased, whitespace-collapsed title and body.
func FirstSentence ¶
FirstSentence returns the first sentence of body on one line. It is the fallback summary when a write carries none; a '.' only ends a sentence when it ends the text or is followed by a space, so versions and paths survive.
func Slug ¶
Slug derives a stable id stem from a title: lowercase ASCII letters and digits joined by '-'. Titles with non-ASCII letters (e.g. Chinese) get a short hash of the normalized title appended so distinct titles stay distinct; a title with no ASCII letters at all becomes the hash alone.
func UniqueID ¶
UniqueID returns base, or base-2, base-3, ... until the id is valid and taken reports false. A base that is not a valid id stem is slugged first, and long bases are cut so the suffix always fits MaxIDLen.
func ValidateID ¶
ValidateID rejects ids that are not safe file-name stems.
Types ¶
type BudgetError ¶
type BudgetError struct {
Scope Scope
Lines, Bytes int // index size after the write
MaxLines, MaxBytes int
}
BudgetError details an ErrOverBudget refusal.
func (*BudgetError) Error ¶
func (e *BudgetError) Error() string
func (*BudgetError) Unwrap ¶
func (e *BudgetError) Unwrap() error
Unwrap lets errors.Is(err, ErrOverBudget) match.
type Entry ¶
type Entry struct {
ID, Title, Body string
Kind Kind
// Summary is the one-sentence description carried by the index line; it
// is metadata, not part of the body.
Summary string
AppliesWhen []string
Updated time.Time
Prov Provenance
}
Entry is one memory item.
type Enumerator ¶
Enumerator is optionally implemented by a backend that can enumerate all readable entries in a scope. It supports rebuildable derived indexes without changing Store's four-method contract.
type Event ¶
type Event struct {
Type string // EventWrite or EventDenied
Scope Scope
Backend string
Action Action
ID string // entry id; empty for a refused add
Kind Kind
Tainted bool
Source string
Reason string // Reason* code, only for EventDenied
Detail string // error text, only for EventDenied
}
Event describes a governed write or refusal.
type Governed ¶
type Governed struct {
// contains filtered or unexported fields
}
Governed applies Policy to every write of the wrapped store and sanitizes everything it reads back. Wrap a Router (or a single backend) with it; all backends get the same governance, the built-in one included.
func NewGoverned ¶
NewGoverned wraps next with policy p, filling in defaults.
func (*Governed) BackendName ¶
BackendName reports the wrapped store's name.
func (*Governed) Index ¶
Index returns the backend index with sanitized titles; lines whose id is not a valid id are dropped because the backend output is untrusted.
func (*Governed) Route ¶
Route exposes the wrapped store's routing so Governed can itself be wrapped or inspected like a Router.
func (*Governed) Write ¶
Write runs the governed write pipeline. The order is part of the contract:
- taint gate (Tainted → Confirm), first so nothing below can bypass it
- Sanitize title and body
- tombstone check on the content fingerprint (add/replace)
- budget check on the simulated index (add/replace)
- backend write
- provenance: Record for add/replace, Tombstone for remove
- memory_write event
Refusals in steps 1-4 never reach the backend and emit memory_denied.
type Index ¶
type Index struct {
Scope Scope
Lines []IndexLine
// Bytes is the size of the index as the backend stores it (for the files
// backend: MEMORY.md including hand-written lines). Backends without a
// stored index may leave it 0; budget checks then use len(Render()).
Bytes int
}
Index is the resident part of a scope: one line per entry.
type IndexLine ¶
type IndexLine struct {
ID string
Title string
Kind Kind
// Summary is the optional one-sentence description shown after the kind.
// Empty renders exactly like the line format before summaries existed.
Summary string
}
IndexLine is the resident one-line summary of an entry.
type Kind ¶
type Kind string
Kind classifies an entry. The four kinds follow the memory tool contract.
const ( KindUser Kind = "user" // who the user is: role, preferences, expertise KindFeedback Kind = "feedback" // guidance on how to work: corrections and confirmed choices KindProject Kind = "project" // facts about ongoing work that the code and git do not show KindReference Kind = "reference" // pointers to external resources )
type Named ¶
type Named interface {
BackendName() string
}
Named is optionally implemented by backends to report a stable name such as "files", "gofer" or "exec" (used in provenance rows and the manifest).
type Op ¶
type Op struct {
Action Action
ID string
Title string
Body string
Kind Kind
// Summary is the one-sentence description stored in the index line. add
// fills it from the body's first sentence when it is empty; replace keeps
// the stored summary when it is empty.
Summary string
// AppliesWhen records versions, environments or other conditions under
// which this entry remains useful. It is optional and never enters Index.
AppliesWhen []string
Prov Provenance
}
Op is a write request.
- add: Title, Body and Kind are required; ID must be empty because the backend derives it from the title (see Slug and UniqueID).
- replace: ID, Title and Body are required; the entry is rewritten as a whole. An empty Kind keeps the stored kind.
- remove: only ID is used. Backends return the removed entry (with its title and body) so the governance layer can tombstone its content.
type Policy ¶
type Policy struct {
// Tainted reports whether the current session has seen external content.
// nil means never tainted.
Tainted func(ctx context.Context) bool
// Confirm asks the user to approve a write from a tainted session; a nil
// error approves. A nil Confirm refuses every tainted write
// (ErrNeedsConfirmation). It receives the op as requested, before
// sanitizing, so implementations should sanitize what they display.
Confirm func(ctx context.Context, s Scope, op Op) error
// Sanitize cleans titles and bodies on write and all text read back from
// the backend. Defaults to redact.Clean.
Sanitize func(string) string
// Budget limits each scope's index. Zero fields use the defaults.
Budget Budget
// Observe receives memory_write / memory_denied events. Optional.
Observe func(ctx context.Context, ev Event)
// Provenance stores provenance and tombstones for backends that do not
// implement ProvenanceStore themselves. Optional: without either, writes
// are not recorded and tombstones are not enforced.
Provenance ProvenanceStore
}
Policy carries everything Governed needs from the host. agentcore does not know how sessions, taint or confirmations are stored.
type Provenance ¶
type Provenance struct {
SessionID string
TurnID string
Source string // source category, e.g. "tool", "user", "import"
Tainted bool // the writing session had seen external content
}
Provenance records where an entry came from.
type ProvenanceStore ¶
type ProvenanceStore interface {
// Record upserts the provenance of an added or replaced entry together
// with the fingerprint of its content (see Fingerprint).
Record(ctx context.Context, backend string, s Scope, e Entry, fingerprint string) error
// Tombstone marks a removed entry; fingerprint is its content fingerprint
// so the same content cannot be written back silently.
Tombstone(ctx context.Context, backend string, s Scope, id, fingerprint string) error
// IsTombstoned reports whether content with this fingerprint was removed
// from the scope before.
IsTombstoned(ctx context.Context, backend string, s Scope, fingerprint string) (bool, error)
}
ProvenanceStore keeps provenance and tombstones for entries. A backend that can store them itself implements it; otherwise the host injects one through Policy.Provenance (suga uses a SQLite side table). backend is the backend name (see Named) so one store can serve several backends.
type Resolver ¶
Resolver is implemented by stores that dispatch scopes to other stores (Router). Governed uses it to find the concrete backend of a scope for its name and ProvenanceStore capability.
type RouteInfo ¶
type RouteInfo struct {
Scope string // scope kind
Backend string // backend name (Named), "unknown" when not reported
}
RouteInfo names the backend serving one scope kind.
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router dispatches each call to the backend registered for the scope kind (user, project, people). The usual wiring is NewGoverned(router, policy): governance runs once, then the router picks the backend.
func (*Router) Backends ¶
Backends lists the registered scope kinds and their backend names, sorted by scope kind.
type Scope ¶
Scope selects one memory namespace: {"user",""}, {"project","<key>"} or the reserved {"people","<name>"}.
func ParseScope ¶
ParseScope parses "user", "project:<key>" or "people:<name>". The key is everything after the first colon.
func ProjectScope ¶
ProjectScope returns the scope of the project identified by key.
type Store ¶
type Store interface {
// Index returns the resident part of the scope: one line per entry.
Index(ctx context.Context, s Scope) (Index, error)
// Get returns one entry by id.
Get(ctx context.Context, s Scope, id string) (Entry, error)
// Write applies an add, replace or remove op and returns the resulting
// entry; for remove it returns the entry as it was before removal.
Write(ctx context.Context, s Scope, op Op) (Entry, error)
// Search returns entries matching q, at most limit (<= 0: backend default).
Search(ctx context.Context, s Scope, q string, limit int) ([]Hit, error)
}
Store is implemented by every memory backend (files, gofer, exec) and by the Governed and Router wrappers.
Backends report a missing entry with an error wrapping ErrNotFound and invalid input with ErrInvalid. Content returned by a backend is treated as untrusted; Governed sanitizes it on the way out.
type Summarizer ¶
Summarizer is optionally implemented by a backend that can rewrite the one-sentence index summary of an entry without touching its body or title. It backs the maintenance command that fills missing summaries.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package execstore is a memory.Store backed by an external command that speaks the suga exec protocol v1 (see package extproc): every operation runs the command once, writes one JSON request line to its stdin and reads one JSON response line from its stdout.
|
Package execstore is a memory.Store backed by an external command that speaks the suga exec protocol v1 (see package extproc): every operation runs the command once, writes one JSON request line to its stdin and reads one JSON response line from its stdout. |
|
Package files is the built-in memory backend: per scope one MEMORY.md index plus one Markdown file per entry.
|
Package files is the built-in memory backend: per scope one MEMORY.md index plus one Markdown file per entry. |