memory

package
v0.1.13 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package memory provides structured, inspectable long-term memory.

Index

Constants

View Source 
const (
	KindFact       = "fact"
	KindPreference = "preference"
	KindPerson     = "person"
	KindEpisode    = "episode"
	KindInsight    = "insight"
)

Kind values for typed memory rows.

View Source 
const (
	SourceChat          = "chat"
	SourceConsolidation = "consolidation"
	SourceOperator      = "operator"
)

Source values.

View Source 
const (
	ToolStore  = "memory_store"
	ToolRecall = "memory_recall"
	ToolForget = "memory_forget"
)

Tool names exposed to the model (builtin, not MCP-prefixed).

View Source 
const PersonaPrecedenceNote = `` /* 373-byte string literal not displayed */

PersonaPrecedenceNote is appended to the system prompt when memory is enabled.

Variables

This section is empty.

Functions

func FormatHydration 

func FormatHydration(entries []Entry) string

FormatHydration renders entries as the compact prompt block.

func IsMemoryTool 

func IsMemoryTool(name string) bool

IsMemoryTool reports whether name is a builtin memory tool.

func ToolDefs 

func ToolDefs() []provider.ToolDef

ToolDefs returns the three builtin memory tool schemas.

func ValidateKind 

func ValidateKind(kind string) error

ValidateKind checks a memory kind string.

Types

type Builtin 

type Builtin struct {
	// contains filtered or unexported fields
}

Builtin is the SQLite + FTS5 memory backend in gantry.db.

func Open 

func Open(dataDir string) (*Builtin, error)

Open opens (or creates) memory tables in dataDir/gantry.db.

func OpenDB 

func OpenDB(db *sql.DB) (*Builtin, error)

OpenDB attaches memory schema to an existing DB handle (shared with session).

func (*Builtin) ApplyConsolidation added in v0.1.12 

func (b *Builtin) ApplyConsolidation(ctx context.Context, episodeIDs []int64, items []consolidateItem, allowedSupersede map[int64]bool) (int, error)

ApplyConsolidation stores durable rows and marks episodes in one transaction. allowedSupersede restricts supersede targets to the prompted episode batch.

func (*Builtin) Close 

func (b *Builtin) Close() error

Close closes the DB when Open owned it.

func (*Builtin) Forget 

func (b *Builtin) Forget(ctx context.Context, id int64) error

Forget hard-deletes a row by id.

func (*Builtin) ForgetQuery 

func (b *Builtin) ForgetQuery(ctx context.Context, query string) (int, error)

ForgetQuery deletes FTS matches for query (correctability).

func (*Builtin) Hydrate 

func (b *Builtin) Hydrate(ctx context.Context, query string, limit int) ([]Entry, error)

Hydrate returns active durable rows plus FTS hits for query (cap ~30).

func (*Builtin) ListUnconsolidatedEpisodes 

func (b *Builtin) ListUnconsolidatedEpisodes(ctx context.Context, limit int) ([]Entry, error)

ListUnconsolidatedEpisodes returns episode rows awaiting consolidation.

func (*Builtin) MarkConsolidated 

func (b *Builtin) MarkConsolidated(ctx context.Context, ids []int64) error

MarkConsolidated marks episode ids as processed by the consolidator.

func (*Builtin) Recall 

func (b *Builtin) Recall(ctx context.Context, query string, limit int) ([]Entry, error)

Recall runs FTS5 + recency ranking.

func (*Builtin) RecordConsolidateFailure added in v0.1.12 

func (b *Builtin) RecordConsolidateFailure(ctx context.Context, ids []int64, maxAttempts int) error

RecordConsolidateFailure bumps attempts; quarantines after maxAttempts.

func (*Builtin) Store 

func (b *Builtin) Store(ctx context.Context, kind, subject, content string) (Entry, error)

Store inserts one atomic memory row.

func (*Builtin) StoreConsolidated 

func (b *Builtin) StoreConsolidated(ctx context.Context, kind, subject, content string) (Entry, error)

StoreConsolidated inserts a consolidation-sourced row.

func (*Builtin) Supersede 

func (b *Builtin) Supersede(ctx context.Context, oldID, newID int64) error

Supersede links oldID → newID without deleting.

type Composite 

type Composite struct {
	Memory        Tools
	Other         ToolRunner
	HideMCPServer string // optional: strip {server}__memory_* from Other.Tools()
}

Composite merges builtin memory tools with an optional MCP/other runner. When HideMCPServer is set (mcp memory backend), that server's memory_* tools are omitted from the listing so the model only sees the unprefixed names.

func (Composite) Call 

func (c Composite) Call(ctx context.Context, name string, arguments json.RawMessage) (string, error)

Call routes memory_* to the memory backend; everything else to Other.

func (Composite) ToolCount 

func (c Composite) ToolCount() int

ToolCount returns the number of tools exposed to the model.

func (Composite) Tools 

func (c Composite) Tools() []provider.ToolDef

Tools returns memory defs first, then other tools.

type Consolidator 

type Consolidator struct {
	Store     *Builtin
	Completer provider.Completer
	Interval  time.Duration
	BatchSize int
	Logger    *slog.Logger
}

Consolidator runs the cheap "sleep cycle" over unconsolidated episodes. Builtin backend only.

func (*Consolidator) Pass 

func (c *Consolidator) Pass(ctx context.Context)

Pass runs one consolidation cycle (bounded batch).

func (*Consolidator) Start 

func (c *Consolidator) Start(ctx context.Context)

Start runs consolidation passes on Interval until ctx is cancelled. Interval <= 0 means disabled (returns immediately).

type Entry 

type Entry struct {
	ID           int64
	Kind         string
	Subject      string
	Content      string
	Source       string
	Confidence   float64
	CreatedAt    time.Time
	UpdatedAt    time.Time
	ExpiresAt    *time.Time
	SupersededBy *int64
}

Entry is one structured memory row.

type MCPAdapter 

type MCPAdapter struct {
	Caller MCPCaller
	Server string
}

MCPAdapter routes memory tools to an MCP server from the manifest (MEMORY_BACKEND=mcp:<server-name>). Expected remote tools: 

{server}__memory_store | {server}__memory_recall | {server}__memory_forget

func NewMCPAdapter 

func NewMCPAdapter(caller MCPCaller, server string) (*MCPAdapter, error)

NewMCPAdapter builds an adapter for server name (without mcp: prefix).

func (*MCPAdapter) Close 

func (a *MCPAdapter) Close() error

Close is a no-op (MCP host owns the connection).

func (*MCPAdapter) Forget 

func (a *MCPAdapter) Forget(ctx context.Context, id int64) error

Forget calls remote memory_forget by id.

func (*MCPAdapter) ForgetQuery 

func (a *MCPAdapter) ForgetQuery(ctx context.Context, query string) (int, error)

ForgetQuery calls remote memory_forget by query.

func (*MCPAdapter) Hydrate 

func (a *MCPAdapter) Hydrate(ctx context.Context, query string, limit int) ([]Entry, error)

Hydrate uses recall with the current query (remote backends vary).

func (*MCPAdapter) Recall 

func (a *MCPAdapter) Recall(ctx context.Context, query string, limit int) ([]Entry, error)

Recall calls remote memory_recall.

func (*MCPAdapter) Store 

func (a *MCPAdapter) Store(ctx context.Context, kind, subject, content string) (Entry, error)

Store calls remote memory_store.

type MCPCaller 

type MCPCaller interface {
	Call(ctx context.Context, toolName string, arguments json.RawMessage) (string, error)
}

MCPCaller is the subset of mcp.Host needed by the memory adapter.

type Memory 

type Memory interface {
	Store(ctx context.Context, kind, subject, content string) (Entry, error)
	Recall(ctx context.Context, query string, limit int) ([]Entry, error)
	Forget(ctx context.Context, id int64) error
	ForgetQuery(ctx context.Context, query string) (int, error)
	Hydrate(ctx context.Context, query string, limit int) ([]Entry, error)
	Close() error
}

Memory is the swappable memory backend surface (tools + hydration).

type ToolRunner 

type ToolRunner interface {
	Tools() []provider.ToolDef
	Call(ctx context.Context, name string, arguments json.RawMessage) (string, error)
	ToolCount() int
}

ToolRunner is MCP (or other) tools merged with builtin memory tools.

type Tools 

type Tools struct {
	Backend Memory
}

Tools adapts a Memory backend into agent tool defs / calls.

func (Tools) Call 

func (t Tools) Call(ctx context.Context, name string, arguments json.RawMessage) (string, error)

Call executes a builtin memory tool.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.