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
- func New(r *memory.Router, opts Options) ([]tool.Tool, error)
- func PermittedRecallMounts(ctx context.Context, gate *permissions.Gate, r *memory.Router, query string) []string
- type ForgetArgs
- type ForgetResult
- type Options
- type PersistArgs
- type PersistResult
- type RecallArgs
- type RecallResult
- type RecalledItem
Constants ¶
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 ¶
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.