config

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Jun 9, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package config loads and validates .agent-memory/meta/manifest.yaml. The manifest holds operational settings (budgets, staging TTL, security flags, git policy, per-category approval overrides) — distinct from the per-category structural rules in internal/schema.

See docs/patterns/configuration-loading.md and design doc v0.4.1 §26.

Index

Constants

View Source
const CurrentStoreFormatVersion = 1

CurrentStoreFormatVersion is the on-disk store-format version this binary reads and writes. It is a monotonic integer, deliberately separate from the human/product Manifest.Version string: the persisted format evolves on its own schedule, and migrations key off this number.

Bump it only when the persisted format changes in a way that needs a migration step, and add the corresponding handling in migrateManifest (for in-memory normalisation) and/or an explicit store migration (for changes that must rewrite files — see migrateManifest's note on why those must not run on read paths).

View Source
const DefaultStorePath = ".agent-memory"

DefaultStorePath is the store directory within a referenced repo.

View Source
const DefaultStorePriority = 0.8

DefaultStorePriority is the ranking multiplier applied to a referenced store's results (the local store is 1.0). It is applied as a multiplier on the existing negative-BM25-derived score (see internal/index/ranking.go), so a value below 1 PENALIZES a store relative to local — the intended default for landscape memory. Do not "fix the sign".

View Source
const StoreModeReadOnly = "read-only"

StoreModeReadOnly is the only supported mode in slice 1: a consuming repo reads a referenced store but never writes to it. read-write (cross-repo propose) is a later design.

View Source
const StoresLockName = "stores.lock"

StoresLockName is the committed lockfile, under meta/.

View Source
const StoresLockVersion = 1

StoresLockVersion is the lockfile format version.

Variables

View Source
var ErrStoreFormatTooNew = errors.New("store format newer than supported; upgrade agent-memory")

ErrStoreFormatTooNew is returned when a store declares a format version newer than this binary supports. We fail closed rather than risk misreading a future layout with an older binary.

Functions

func WriteDefault

func WriteDefault(path, projectName string) error

WriteDefault writes the recommended manifest to path, with Project.Name set to projectName. Used by `agent-memory init` (T1.10).

func WriteManifest

func WriteManifest(path string, m *Manifest) error

WriteManifest serialises m to path atomically.

func WriteStoresLock added in v0.5.0

func WriteStoresLock(path string, l *StoresLock) error

WriteStoresLock serialises l to path atomically. yaml.v3 emits map keys in sorted order, so the committed lock is deterministic.

Types

type AllowlistLimitsSpec

type AllowlistLimitsSpec struct {
	MaxBytesPerFile   int `yaml:"max_bytes_per_file,omitempty"`
	MaxRegionsPerFile int `yaml:"max_regions_per_file,omitempty"`
	MaxBytesPerRegion int `yaml:"max_bytes_per_region,omitempty"`
}

AllowlistLimitsSpec caps how much content allowlist-marker regions can cover in a single file. A limit of 0 means "disabled".

The allowlist mechanism is intentionally a per-region escape hatch for documenting token formats (`ghp_AaBbCc...example, not real`). Without limits, a malicious or careless agent could wrap multi-KB regions around real credentials and bypass the scanner entirely. These caps keep allowlists in their intended size range.

Defaults (DefaultManifest):

MaxBytesPerFile:   1024 — five 200-byte format examples fit comfortably
MaxRegionsPerFile: 10   — more regions usually signals over-escaping
MaxBytesPerRegion: 512  — single largest region; a token + surrounding prose

type ApprovalPolicy

type ApprovalPolicy struct {
	Decisions       schema.ApprovalMode `yaml:"decisions"`
	Conventions     schema.ApprovalMode `yaml:"conventions"`
	Modules         schema.ApprovalMode `yaml:"modules"`
	PitfallsReplace schema.ApprovalMode `yaml:"pitfalls_replace"`
	PitfallsAppend  schema.ApprovalMode `yaml:"pitfalls_append"`
	Archive         schema.ApprovalMode `yaml:"archive"`
	Current         schema.ApprovalMode `yaml:"current"`
	CurrentShared   schema.ApprovalMode `yaml:"current_shared"`
	Sessions        schema.ApprovalMode `yaml:"sessions"`
	Index           schema.ApprovalMode `yaml:"index"`
}

ApprovalPolicy maps category / operation kinds to ApprovalMode. The distinction between "pitfalls_append" and "pitfalls_replace" lives here (not in schema) because it's per-operation, not per-file.

type Archive

type Archive struct {
	Enabled            bool `yaml:"enabled"`
	StaleThresholdDays int  `yaml:"stale_threshold_days"`
}

Archive holds archival-compaction settings.

type Budgets

type Budgets struct {
	BootstrapChars    int `yaml:"bootstrap_chars"`
	FetchContextChars int `yaml:"fetch_context_chars"`
	MaxFileChars      int `yaml:"max_file_chars"`
}

Budgets caps various character / line budgets used by fetch_context and the size validator.

type Concurrency

type Concurrency struct {
	LockTTLSeconds     int `yaml:"lock_ttl_seconds,omitempty"`
	WaitTimeoutSeconds int `yaml:"wait_timeout_seconds"`
}

Concurrency holds lock-related tunables.

LockTTLSeconds is accepted from legacy v0.4 manifests but intentionally IGNORED by the v0.4.1 lock implementation. v0.4.1 §11 replaced TTL-based locking with OS-level advisory locks (gofrs/flock); the kernel handles release on process death, so application-level TTL has nothing to enforce. The field is tagged omitempty so fresh manifests don't carry it forward.

type Eval

type Eval struct {
	BenchmarkCorpusURL string `yaml:"benchmark_corpus_url,omitempty"`
}

Eval is optional and used by the M8 benchmark runner.

type Git

type Git struct {
	TrackLocal           bool   `yaml:"track_local"`
	TrackSessions        bool   `yaml:"track_sessions"`
	AutoStageChanges     bool   `yaml:"auto_stage_changes"`
	AutoCommit           bool   `yaml:"auto_commit"`
	CommitMessagePrefix  string `yaml:"commit_message_prefix"`
	MergeDriverInstalled bool   `yaml:"merge_driver_installed"`
}

Git holds git-integration settings.

type LocalState

type LocalState struct {
	PerBranch                 bool `yaml:"per_branch"`
	SharedFileEnabled         bool `yaml:"shared_file_enabled"`
	CleanupOrphansWarningDays int  `yaml:"cleanup_orphans_warning_days"`
}

LocalState holds per-branch local-state behaviour.

type LockedStore added in v0.5.0

type LockedStore struct {
	Source            string `yaml:"source"`
	RequestedRevision string `yaml:"requested_revision,omitempty"`
	ResolvedCommit    string `yaml:"resolved_commit,omitempty"` // empty when Unlocked
	ResolvedAt        string `yaml:"resolved_at,omitempty"`     // RFC 3339; set by sync
	StorePath         string `yaml:"store_path,omitempty"`
	// Unlocked marks a local-path source that is not a git work tree: its
	// content is not pinned to a commit, so the entry is not reproducible.
	// Intended for dev / monorepo use; status surfaces a warning.
	Unlocked bool `yaml:"unlocked,omitempty"`
}

LockedStore records the resolution of one store at sync time.

type Manifest

type Manifest struct {
	Version            string      `yaml:"version"`
	StoreFormatVersion int         `yaml:"store_format_version,omitempty"`
	Project            Project     `yaml:"project"`
	Budgets            Budgets     `yaml:"budgets"`
	Updates            Updates     `yaml:"updates"`
	Staging            Staging     `yaml:"staging"`
	Security           Security    `yaml:"security"`
	Git                Git         `yaml:"git"`
	Archive            Archive     `yaml:"archive"`
	Concurrency        Concurrency `yaml:"concurrency"`
	LocalState         LocalState  `yaml:"local_state"`
	Sessions           Sessions    `yaml:"sessions"`
	Eval               Eval        `yaml:"eval,omitempty"`
	Stores             []Store     `yaml:"stores,omitempty"`
}

Manifest is the deserialisation target for manifest.yaml.

func DefaultManifest

func DefaultManifest() *Manifest

DefaultManifest returns the recommended manifest from design doc §26.1.

func LoadManifest

func LoadManifest(path string) (*Manifest, error)

LoadManifest reads manifest.yaml from path. Missing fields are filled from DefaultManifest — yaml.v3 merges into the pre-populated struct, so users can override just the fields they care about.

func (*Manifest) Validate

func (m *Manifest) Validate() error

Validate checks basic invariants on m:

  • Version is non-empty.
  • Every approval mode is a recognised ApprovalMode.
  • Budgets and TTL values are positive.

Heavier semantic checks (e.g., that Index is server_only) live in the downstream code that consumes the manifest, not in the loader.

type Project

type Project struct {
	Name string `yaml:"name"`
	Root string `yaml:"root"`
}

Project identifies the repository the manifest belongs to.

type Security

type Security struct {
	SecretScan                    bool                `yaml:"secret_scan"`
	RejectUntrustedDurableUpdates bool                `yaml:"reject_untrusted_durable_updates"`
	PIIScan                       bool                `yaml:"pii_scan"`
	PIIScanEmail                  bool                `yaml:"pii_scan_email,omitempty"`
	AllowlistLimits               AllowlistLimitsSpec `yaml:"allowlist_limits,omitempty"`
}

Security holds security-engine policy.

type Sessions

type Sessions struct {
	PerBranch bool `yaml:"per_branch"`
}

Sessions holds session-recording behaviour.

type Staging

type Staging struct {
	TTLSeconds int `yaml:"ttl_seconds"`
}

Staging holds staging-directory policy.

type Store added in v0.5.0

type Store struct {
	Name               string   `yaml:"name"`
	Source             string   `yaml:"source"`                        // git URL or local path
	Revision           string   `yaml:"revision,omitempty"`            // branch/tag/commit; default branch if empty
	Path               string   `yaml:"path,omitempty"`                // store dir within the repo; default ".agent-memory"
	Mode               string   `yaml:"mode,omitempty"`                // "read-only" (default/only in slice 1)
	PriorityMultiplier *float64 `yaml:"priority_multiplier,omitempty"` // omitted = default (0.8); must be > 0 if set
}

Store is one referenced landscape store.

func (Store) EffectiveMode added in v0.5.0

func (s Store) EffectiveMode() string

EffectiveMode returns the store mode, defaulting to read-only.

func (Store) Priority added in v0.5.0

func (s Store) Priority() float64

Priority returns the ranking multiplier, defaulting to DefaultStorePriority when unset. A set value is guaranteed > 0 by validateStores, so there is no ambiguity between "unset" and an explicit zero.

func (Store) StorePath added in v0.5.0

func (s Store) StorePath() string

StorePath returns the in-repo store directory, defaulting to ".agent-memory".

type StoresLock added in v0.5.0

type StoresLock struct {
	Version int                    `yaml:"version"`
	Stores  map[string]LockedStore `yaml:"stores"`
}

StoresLock is the deserialisation target for meta/stores.lock.

func LoadStoresLock added in v0.5.0

func LoadStoresLock(path string) (*StoresLock, error)

LoadStoresLock reads meta/stores.lock. A missing file is not an error — it means nothing has been synced yet, so an empty lock is returned. A lock written by a newer format fails closed.

func NewStoresLock added in v0.5.0

func NewStoresLock() *StoresLock

NewStoresLock returns an empty, current-version lock.

type Updates

type Updates struct {
	Approval ApprovalPolicy `yaml:"approval"`
}

Updates holds the per-operation approval overrides.

Jump to

Keyboard shortcuts

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