memory

Documentation

Overview

Package memory persists durable, agent-visible facts about the user's workspace ("build command is X", "issue #42 root cause is Y") and the user's broader environment ("prefer pnpm over npm", "VPN URL is Z").

Three layers:

• global instructions: <XDG_CONFIG_HOME>/ub/instructions.md — hand-written user preferences that travel with the user.
• project instructions: <workspace>/AGENTS.md — hand-written project facts that travel with the project. (Read-only for this package; loaded by the prompt harness.)
• auto memory: <XDG_STATE_HOME>/ub/memory/<project-key>/memory.md — machine-appended facts keyed by project, never committed to git.

Auto memory entries are organized by category (preference, project, pattern, decision, debug, general) within a single markdown file. The file format uses H2 section headings for categories and bullet items for entries, so users can hand-edit without breaking the runtime.

Index

• Constants
• func Append(workspaceRoot string, scope Scope, category Category, text string) (string, string, error)
• func Path(workspaceRoot string, scope Scope) (string, error)
• func Read(workspaceRoot string, maxChars int) string
• func ValidCategory(c string) bool
• func ValidScope(s string) bool
• type Category
• type Entry
  • func Recall(workspaceRoot string, query string, category Category) ([]Entry, error)
• type Scope

Constants

const DefaultCategory = CatGeneral

DefaultCategory is used when no category is specified.

const DefaultReadMaxChars = 4000

DefaultReadMaxChars is the default budget used when agent.Options does not specify one.

Functions

func Append

func Append(workspaceRoot string, scope Scope, category Category, text string) (string, string, error)

Append writes a new entry to the scope's memory file. Auto-memory entries are de-duplicated within the same category: similar existing text is updated (timestamp refreshed, text replaced) instead of appending a duplicate. Global instructions are append-only so hand-written content is never rewritten by the structured auto-memory parser.

Returns the absolute path of the file and a human-readable heading string.

func Path

func Path(workspaceRoot string, scope Scope) (string, error)

Path returns the absolute path of the memory file for one scope.

• ScopeAuto: $XDG_STATE_HOME/ub/memory/<project-key>/memory.md
• ScopeGlobal: $XDG_CONFIG_HOME/ub/instructions.md

workspaceRoot MUST be non-empty for ScopeAuto.

func Read

func Read(workspaceRoot string, maxChars int) string

Read returns the concatenated memory the agent should see this turn: global instructions first, then auto memory entries, with section markers so the model can tell them apart.

When maxChars > 0 and the combined text exceeds the budget, auto memory entries are included by category priority (preference first, debug last). Within the same category, newer entries are preferred. Global instructions are always kept. A "... [memory truncated]" marker is prepended when some entries are dropped.

func ValidCategory

func ValidCategory(c string) bool

ValidCategory reports whether c is a recognized category.

func ValidScope

func ValidScope(s string) bool

ValidScope reports whether s is one of the supported scope values.

Types

type Category

type Category string

Category classifies a memory entry for prioritized injection.

const (
	CatPreference Category = "preference" // user preferences — always injected
	CatProject    Category = "project"    // project facts — high priority
	CatPattern    Category = "pattern"    // code style/patterns — medium
	CatDecision   Category = "decision"   // architecture decisions — medium
	CatDebug      Category = "debug"      // debug notes — low, decays
	CatGeneral    Category = "general"    // misc — low
)

type Entry

type Entry struct {
	Category  Category
	Timestamp time.Time
	Text      string
}

Entry is one structured memory record.

func Recall

func Recall(workspaceRoot string, query string, category Category) ([]Entry, error)

Recall searches auto memory entries matching a query. If query is empty, all entries are returned (optionally filtered by category). Returns an empty slice when no memory file exists.

type Scope

type Scope string

Scope selects which memory source an operation targets.

const (
	ScopeAuto      Scope = "auto"      // project auto memory (default)
	ScopeGlobal    Scope = "global"    // global hand-written instructions
	ScopeWorkspace Scope = "workspace" // deprecated alias for auto; kept for API compat
)