memory

package
v0.54.7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 14 Imported by: 0

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

View Source
const (
	DefaultMaxLines = 200
	DefaultMaxBytes = 16 * 1024
)

Default index budget per scope (design D6). Over-budget writes fail; the index is never truncated silently.

View Source
const (
	EventWrite  = "memory_write"
	EventDenied = "memory_denied"
)

Event types passed to Policy.Observe.

View Source
const (
	ReasonInvalid           = "invalid"
	ReasonNeedsConfirmation = "needs_confirmation"
	ReasonDenied            = "denied"
	ReasonTombstoned        = "tombstoned"
	ReasonOverBudget        = "over_budget"
)

Deny reasons carried by memory_denied events.

View Source
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.

View Source
const MaxIDLen = 80

MaxIDLen bounds entry ids; slugs are cut shorter to leave room for suffixes.

View Source
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

View Source
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

func BackendName(s Store) string

BackendName returns s's Named name, or "unknown".

func CleanSummary

func CleanSummary(s string) string

CleanSummary folds s onto one line (runs of whitespace become one space) and truncates it to SummaryMaxRunes runes.

func Fingerprint

func Fingerprint(title, body string) string

Fingerprint identifies entry content for tombstones: sha256 over the lowercased, whitespace-collapsed title and body.

func FirstSentence

func FirstSentence(body string) string

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

func Slug(title string) string

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

func UniqueID(base string, taken func(id string) bool) string

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

func ValidateID(id string) error

ValidateID rejects ids that are not safe file-name stems.

Types

type Action

type Action string

Action is a write operation.

const (
	ActionAdd     Action = "add"
	ActionReplace Action = "replace"
	ActionRemove  Action = "remove"
)

type Budget

type Budget struct {
	MaxLines int
	MaxBytes int
}

Budget limits the index of one scope. Zero or negative fields use the defaults.

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

type Enumerator interface {
	Entries(ctx context.Context, s Scope) ([]Entry, error)
}

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

func NewGoverned(next Store, p Policy) *Governed

NewGoverned wraps next with policy p, filling in defaults.

func (*Governed) BackendName

func (g *Governed) BackendName() string

BackendName reports the wrapped store's name.

func (*Governed) Get

func (g *Governed) Get(ctx context.Context, s Scope, id string) (Entry, error)

Get returns a sanitized entry.

func (*Governed) Index

func (g *Governed) Index(ctx context.Context, s Scope) (Index, error)

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

func (g *Governed) Route(s Scope) (Store, error)

Route exposes the wrapped store's routing so Governed can itself be wrapped or inspected like a Router.

func (*Governed) Search

func (g *Governed) Search(ctx context.Context, s Scope, q string, limit int) ([]Hit, error)

Search returns sanitized hits; hits with invalid ids are dropped.

func (*Governed) Write

func (g *Governed) Write(ctx context.Context, s Scope, op Op) (Entry, error)

Write runs the governed write pipeline. The order is part of the contract:

  1. taint gate (Tainted → Confirm), first so nothing below can bypass it
  2. Sanitize title and body
  3. tombstone check on the content fingerprint (add/replace)
  4. budget check on the simulated index (add/replace)
  5. backend write
  6. provenance: Record for add/replace, Tombstone for remove
  7. memory_write event

Refusals in steps 1-4 never reach the backend and emit memory_denied.

type Hit

type Hit struct {
	ID      string
	Title   string
	Kind    Kind
	Snippet string
	Updated time.Time
}

Hit is one search result.

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.

func (Index) Render

func (ix Index) Render() string

Render returns the text injected into the system prompt: a heading naming the scope followed by one line per entry. An empty index renders as "".

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.

func (IndexLine) Render

func (l IndexLine) Render() string

Render formats the line as it appears in the prompt index.

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
)

func Kinds

func Kinds() []Kind

Kinds lists the valid kinds in their canonical order.

func ParseKind

func ParseKind(s string) (Kind, error)

ParseKind converts s to a Kind, rejecting unknown values.

func (Kind) Valid

func (k Kind) Valid() bool

Valid reports whether k is one of the four kinds.

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.

func (Op) Validate

func (op Op) Validate() error

Validate checks the shape of the op before any policy runs. Title and body emptiness is re-checked after sanitizing by Governed.

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

type Resolver interface {
	Route(s Scope) (Store, error)
}

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 NewRouter

func NewRouter() *Router

NewRouter returns an empty router.

func (*Router) Backends

func (r *Router) Backends() []RouteInfo

Backends lists the registered scope kinds and their backend names, sorted by scope kind.

func (*Router) Get

func (r *Router) Get(ctx context.Context, s Scope, id string) (Entry, error)

Get implements Store.

func (*Router) Index

func (r *Router) Index(ctx context.Context, s Scope) (Index, error)

Index implements Store.

func (*Router) Register

func (r *Router) Register(scopeKind string, s Store) error

Register sets the backend for a scope kind, replacing any previous one.

func (*Router) Route

func (r *Router) Route(s Scope) (Store, error)

Route returns the backend for s or an ErrNoBackend error.

func (*Router) Search

func (r *Router) Search(ctx context.Context, s Scope, q string, limit int) ([]Hit, error)

Search implements Store.

func (*Router) Write

func (r *Router) Write(ctx context.Context, s Scope, op Op) (Entry, error)

Write implements Store.

type Scope

type Scope struct {
	Kind string
	Key  string
}

Scope selects one memory namespace: {"user",""}, {"project","<key>"} or the reserved {"people","<name>"}.

func ParseScope

func ParseScope(v string) (Scope, error)

ParseScope parses "user", "project:<key>" or "people:<name>". The key is everything after the first colon.

func ProjectScope

func ProjectScope(key string) Scope

ProjectScope returns the scope of the project identified by key.

func UserScope

func UserScope() Scope

UserScope returns the user scope.

func (Scope) String

func (s Scope) String() string

String renders the scope as "user" or "<kind>:<key>".

func (Scope) Validate

func (s Scope) Validate() error

Validate checks the scope kind and key: user has no key, project and people require one, and keys must be a single printable line.

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

type Summarizer interface {
	SetSummary(ctx context.Context, s Scope, id, summary string) error
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL