memtools

package
v3.2.0-rc.1 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package memtools builds the model-facing long-term memory tools (recall_memory, persist_memory, forget_memory) over a *memory.Router (#948, docs/memory-service-design.md "Model-facing tools").

Each handler calls the permission gate itself with a mount-qualified key ("mount=<mount> ..."), so operator policies written in the gate's tool:glob grammar can tell private writes from shared ones, for example "persist_memory:mount=agent *".

The package lives outside pkg/memory so that package stays a leaf that does not import ADK's tool layer or pkg/permissions.

Index

Constants

View Source
const (
	RecallToolName  = "recall_memory"
	PersistToolName = "persist_memory"
	ForgetToolName  = "forget_memory"
)

Tool names. Classified in pkg/permissions (builtinToolClasses), internal/effects (builtinClasses) and pkg/tools (readOnlyBuiltins).

Variables

This section is empty.

Functions

func New

func New(r *memory.Router, opts Options) ([]tool.Tool, error)

New returns the memory tools for r. recall_memory is returned when r has at least one mount; persist_memory and forget_memory are returned only when at least one mount is writable, so a read-only deployment never advertises a write that would always fail. A nil Router yields no tools.

func PermittedRecallMounts

func PermittedRecallMounts(ctx context.Context, gate *permissions.Gate, r *memory.Router, query string) []string

PermittedRecallMounts returns the mounts a recall across "all" may search: every mount except those an operator deny rule names for recall_memory (for example "recall_memory:mount=shared:secret *"). Only deny rules are consulted, so this never prompts and stays usable for pre-turn preload in plan mode. A nil gate permits every mount.

Types

type ForgetArgs

type ForgetArgs struct {
	ID    string `json:"id" jsonschema:"id of the memory to delete, as returned by recall_memory"`
	Mount string `json:"mount" jsonschema:"writable scope that owns the memory: agent or one shared:<pool> name"`
}

ForgetArgs are forget_memory's arguments.

type ForgetResult

type ForgetResult struct {
	Mount   string `json:"mount"`
	ID      string `json:"id"`
	Deleted bool   `json:"deleted"`
	// Warning: see PersistResult.Warning.
	Warning string `json:"warning,omitempty"`
}

ForgetResult is forget_memory's result.

type Options

type Options struct {
	// Gate is consulted inside every handler. Nil leaves the tools
	// ungated, which is what a host that wired no gate has everywhere.
	Gate *permissions.Gate
	// DefaultTopK is used when recall_memory is called without top_k.
	// Zero falls back to the Router's own default.
	DefaultTopK int
}

Options configures New.

type PersistArgs

type PersistArgs struct {
	Fact   string   `` /* 164-byte string literal not displayed */
	Mount  string   `` /* 164-byte string literal not displayed */
	Topics []string `json:"topics,omitempty" jsonschema:"short labels that categorize the fact"`
}

PersistArgs are persist_memory's arguments.

type PersistResult

type PersistResult struct {
	Mount  string                      `json:"mount"`
	Deltas []memory.ConsolidationDelta `json:"deltas"`
	// Warning is set when the write succeeded but recording it in the
	// audit trail failed. The write must not be retried.
	Warning string `json:"warning,omitempty"`
}

PersistResult is persist_memory's result.

type RecallArgs

type RecallArgs struct {
	Query string `json:"query" jsonschema:"the facts, constraints, earlier findings or preferences being looked for, in plain words"`
	Mount string `json:"mount,omitempty" jsonschema:"which mounted scope to search: all (the default), agent, or one shared:<pool> name"`
	TopK  int    `json:"top_k,omitempty" jsonschema:"maximum number of memories to return, 1 to 50"`
}

RecallArgs are recall_memory's arguments.

type RecallResult

type RecallResult struct {
	Items    []RecalledItem        `json:"items"`
	Warnings []memory.MountWarning `json:"warnings,omitempty"`
}

RecallResult is recall_memory's result.

type RecalledItem

type RecalledItem struct {
	ID        string    `json:"id"`
	Mount     string    `json:"mount"`
	ReadOnly  bool      `json:"read_only"`
	Fact      string    `json:"fact"`
	Topics    []string  `json:"topics,omitempty"`
	UpdatedAt time.Time `json:"updated_at,omitzero"`
}

RecalledItem is one memory as recall_memory returns it.

Jump to

Keyboard shortcuts

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