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
- Variables
- func WriteDefault(path, projectName string) error
- func WriteManifest(path string, m *Manifest) error
- func WriteStoresLock(path string, l *StoresLock) error
- type AllowlistLimitsSpec
- type ApprovalPolicy
- type Archive
- type Budgets
- type Concurrency
- type Eval
- type Git
- type LocalState
- type LockedStore
- type Manifest
- type Project
- type Security
- type Sessions
- type Staging
- type Store
- type StoresLock
- type Updates
Constants ¶
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).
const DefaultStorePath = ".agent-memory"
DefaultStorePath is the store directory within a referenced repo.
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".
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.
const StoresLockName = "stores.lock"
StoresLockName is the committed lockfile, under meta/.
const StoresLockVersion = 1
StoresLockVersion is the lockfile format version.
Variables ¶
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 ¶
WriteDefault writes the recommended manifest to path, with Project.Name set to projectName. Used by `agent-memory init` (T1.10).
func WriteManifest ¶
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"`
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"`
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 ¶
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 ¶
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 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
EffectiveMode returns the store mode, defaulting to read-only.
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.