vault

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Apr 17, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	HotMemoryAdmissionCap      = 12
	HotMemoryStaleReviewDays   = 30
	HotMemoryReviewArtifactDir = "memory/maintenance"
	ElderMemoryCap             = 24
	ElderMemoryStaleReviewDays = 365
)
View Source 
const (
	VerificationModeCritical = "critical"

	VerificationStatusVerified       = "verified"
	VerificationStatusReviewRequired = "review_required"
	VerificationStatusMismatch       = "mismatch"
	VerificationStatusUnverified     = "unverified"
	VerificationStatusSourceMissing  = "source_missing"
)

Variables

This section is empty.

Functions

func FormatTuneReport added in v0.5.0 

func FormatTuneReport(report *FSRSTuneReport) string

FormatTuneReport formats the analysis as a human-readable report.

func TrustStageLabel 

func TrustStageLabel(stage int) string

TrustStageLabel returns a human-readable label for a trust stage.

Types

type Dependency 

type Dependency struct {
	Slug string `json:"slug"`
	Type string `json:"type"` // blocks, informs, enhances
}

Dependency represents a typed relationship between missions.

type EpisodeWriteAuthority added in v0.5.0 

type EpisodeWriteAuthority struct {
	ProducingOffice     string
	ProducingSubsystem  string
	StaffingContext     string
	AuthorityScope      string
	TargetDomain        string
	Source              string
	SourceRef           string
	SourceRefs          []string
	ProofRef            string
	PromotionStatus     string
	EventID             string
	LineageID           string
	EventKind           string
	Subject             string
	CueTerms            []string
	AllowApproval       bool
	Mission             string
	WorkItemID          string
	Environment         string
	MemorySecurityClass string
	RelatedFactPaths    []string
	RelatedEpisodePaths []string
	RelatedEntityRefs   []string
	RelatedMissionRefs  []string
}

EpisodeWriteAuthority describes the authority and provenance behind an episodic memory write. Episodes preserve raw or near-raw traces and are the barcode-like identity surface behind later semantic memory.

type FSRSTuneReport added in v0.5.0 

type FSRSTuneReport struct {
	TotalFacts   int
	ByImportance map[string]*importanceBucket
	GeneratedAt  time.Time
	Proposals    map[string]fsrsProposal
}

FSRSTuneReport holds the analysis of current FSRS behavior.

type FactSearchOptions added in v0.5.0 

type FactSearchOptions struct {
	MemoryTemperature string
	VerificationMode  string
	RouteSubject      string
	RouteMission      string
	CapturedByOffice  string
	CueTerms          []string
	TimeBand          string
	WorkItemID        string
	LineageID         string
	Environment       string
}

type FactVerificationResult added in v0.5.0 

type FactVerificationResult struct {
	FactPath           string
	Status             string
	Note               string
	SourceRefs         []string
	ReviewedSourceRefs []string
	VerifiedSourceRefs []string
}

type FactWriteAuthority added in v0.5.0 

type FactWriteAuthority struct {
	ProducingOffice       string
	ProducingSubsystem    string
	StaffingContext       string
	AuthorityScope        string
	TargetDomain          string
	Source                string
	SourceRef             string
	SourceRefs            []string
	ProofRef              string
	PromotionStatus       string
	MemoryTemperature     string
	AllowApproval         bool
	SourceEventID         string
	LineageID             string
	CueTerms              []string
	Mission               string
	WorkItemID            string
	Environment           string
	MemoryProtectionClass string
	MemorySecurityClass   string
	ObservedAt            string
	ValidFrom             string
	ValidTo               string
	TemporalStatus        string
	SupersedesPaths       []string
	RelatedFactPaths      []string
	RelatedEpisodePaths   []string
	RelatedEntityRefs     []string
	RelatedMissionRefs    []string
}

FactWriteAuthority describes the declared authority behind a canonical fact write.

type Filter 

type Filter struct {
	Field   string
	Value   string
	Exclude bool // if true, exclude matches instead of including
}

Filter constrains List results by frontmatter field.

type RecallRequest added in v0.5.0 

type RecallRequest struct {
	Query              string
	Limit              int
	Options            FactSearchOptions
	Harness            string
	Adapter            string
	Mode               string
	ProducingOffice    string
	ProducingSubsystem string
	StaffingContext    string
	WorkItemID         string
}

RecallRequest describes a harness-level retrieval attempt. Unlike plain search, a recall request is durable proof that memory was consulted under a specific mode, through a specific adapter, with a bounded result set.

type RecallResult added in v0.5.0 

type RecallResult struct {
	RecallID           string
	ReceiptPath        string
	Lines              []string
	ResultPaths        []string
	Verification       []FactVerificationResult
	LinkedFactPaths    []string
	LinkedEpisodePaths []string
	LinkedEntityRefs   []string
	LinkedMissionRefs  []string
}

RecallResult is the durable result of a recall operation, including the human-usable lines returned to the caller and the receipt artifact path.

type Vault 

type Vault struct {
	Dir   string
	Index *index.Index
}

Vault provides unified access to the entire vault — brain, memory, atlas, missions.

func New 

func New(dir string, idx *index.Index) *Vault

New creates a Vault rooted at the given directory.

func (*Vault) AddDependency 

func (v *Vault) AddDependency(missionSlug, depSlug, depType string) error

AddDependency adds a typed dependency to a mission's frontmatter. depType must be "blocks", "informs", or "enhances".

func (*Vault) AnalyzeFSRS added in v0.5.0 

func (v *Vault) AnalyzeFSRS() (*FSRSTuneReport, error)

AnalyzeFSRS scans all facts and computes retention statistics per importance tier. Returns a report with over-retained and over-forgotten counts plus proposed adjustments. This is advisory only — it does not modify any configuration.

func (*Vault) ApplyTuneReport added in v0.5.0 

func (v *Vault) ApplyTuneReport(report *FSRSTuneReport) error

ApplyTuneReport promotes a tuning report's proposals into the active FSRS config. Writes the new config to memory/fsrs-config.md with a reference to the source report. This is the explicit apply step — it must be called separately from analysis.

func (*Vault) ArchiveStaleFacts 

func (v *Vault) ArchiveStaleFacts(threshold float64) (int, error)

ArchiveStaleFacts marks facts below a confidence threshold as archived. Returns the number of facts archived. 

func (v *Vault) AuditWikiLinks(write bool) (*WikiLinkAudit, error)

func (*Vault) CanStart 

func (v *Vault) CanStart(missionSlug string) (bool, []string, error)

CanStart checks if all blocking dependencies are satisfied. Returns (canStart, list of unsatisfied blockers).

func (*Vault) CheckAutoCompletion 

func (v *Vault) CheckAutoCompletion(completedSlug string) ([]string, error)

CheckAutoCompletion checks if any group-archetype missions should auto-complete after the given mission was completed. Returns slugs of auto-completed missions.

func (*Vault) CreateMission 

func (v *Vault) CreateMission(title, description, priority string) (string, error)

CreateMission writes a new mission .md file.

func (*Vault) DecayAllBeliefs 

func (v *Vault) DecayAllBeliefs() (int, error)

DecayAllBeliefs sweeps all belief files in atlas/beliefs/ and applies per-predicate linear confidence decay. Returns the number of beliefs updated.

func (*Vault) DecayFacts 

func (v *Vault) DecayFacts() (int, error)

DecayFacts sweeps all fact files and applies FSRS-based confidence decay. Confidence = retrievability R(t) = (1 + t/(9*S))^(-1), floored per importance. Returns the number of facts updated.

func (*Vault) FindCorrections added in v0.5.0 

func (v *Vault) FindCorrections(query string) ([]*markdown.Document, error)

FindCorrections scans memory/corrections/ for corrections whose original field matches the query. Returns matching correction documents.

func (*Vault) FormatCorrectionHints added in v0.5.0 

func (v *Vault) FormatCorrectionHints(query string) string

FormatCorrectionHints formats matching corrections as search-time annotations. These are prepended to search results as hints, not silent rewrites.

func (*Vault) FormatTraceHints added in v0.5.0 

func (v *Vault) FormatTraceHints(query string) string

FormatTraceHints formats matching traces as search-time annotations for inclusion in memory_search results.

func (*Vault) GetBelief 

func (v *Vault) GetBelief(relPath string) (*markdown.Document, error)

GetBelief reads a single belief by relative path.

func (*Vault) GetDependencies 

func (v *Vault) GetDependencies(missionSlug string) ([]map[string]interface{}, error)

GetDependencies returns a mission's dependencies with satisfaction status.

func (*Vault) GetEntity 

func (v *Vault) GetEntity(name string) (*markdown.Document, error)

GetEntity finds an entity by name or slug.

func (*Vault) GetMission 

func (v *Vault) GetMission(slug string) (*markdown.Document, error)

GetMission finds a mission by slug or title.

func (*Vault) GetPR 

func (v *Vault) GetPR(slug string) (*markdown.Document, error)

GetPR reads a single PR by slug or path.

func (*Vault) GetTrustStage 

func (v *Vault) GetTrustStage() (int, map[string]interface{}, error)

GetTrustStage reads the current trust stage from vault/atlas/trust.md. Returns the stage (1-3), the full frontmatter config, and any error.

func (*Vault) List 

func (v *Vault) List(subdir string, filters ...Filter) ([]*markdown.Document, error)

List scans a subdirectory for .md files, optionally filtered.

func (*Vault) ListBeliefs 

func (v *Vault) ListBeliefs(subject string, limit int) ([]*markdown.Document, error)

ListBeliefs returns beliefs, optionally filtered by subject.

func (*Vault) ListBlueprints 

func (v *Vault) ListBlueprints(limit int) ([]*markdown.Document, error)

ListBlueprints returns mission blueprints.

func (*Vault) ListCorrections added in v0.5.0 

func (v *Vault) ListCorrections(limit int) ([]*markdown.Document, error)

ListCorrections returns all correction documents, most recent first.

func (*Vault) ListEntities 

func (v *Vault) ListEntities() ([]*markdown.Document, error)

ListEntities returns all entity documents from atlas/entities/.

func (*Vault) ListFacts 

func (v *Vault) ListFacts(subject string, limit int) ([]*markdown.Document, error)

ListFacts returns memory facts, optionally filtered by subject.

func (*Vault) ListMissions 

func (v *Vault) ListMissions(status string, limit int) ([]*markdown.Document, error)

ListMissions returns missions filtered by status.

func (*Vault) ListPRs 

func (v *Vault) ListPRs(status string) ([]*markdown.Document, error)

ListPRs returns all PRs, optionally filtered by status.

func (*Vault) ListTraces added in v0.5.0 

func (v *Vault) ListTraces(limit int) ([]*markdown.Document, error)

ListTraces returns recent traces, most recent first.

func (*Vault) LoadTunedFSRS added in v0.5.0 

func (v *Vault) LoadTunedFSRS() error

LoadTunedFSRS reads memory/fsrs-config.md and overrides the default FSRS parameters. Called at startup. If the file doesn't exist, defaults are used.

func (*Vault) MergePR 

func (v *Vault) MergePR(relPath, closedBy string) error

MergePR marks a PR as merged and reinforces all linked beliefs. Only the operator should call this — MODUS never closes its own PRs.

func (*Vault) MissionBoard 

func (v *Vault) MissionBoard() map[string][]*markdown.Document

MissionBoard returns missions grouped by status.

func (*Vault) OpenPR 

func (v *Vault) OpenPR(title, openedBy, targetType, targetID string,
	reasoning string, confidence float64, linkedBeliefIDs []string) (string, error)

OpenPR creates a new PR (evolution proposal) in vault/atlas/prs/. Returns the relative path of the created PR file.

func (*Vault) Path 

func (v *Vault) Path(parts ...string) string

Path joins segments onto the vault root.

func (*Vault) Read 

func (v *Vault) Read(relPath string) (*markdown.Document, error)

Read parses a single markdown file by relative path.

func (*Vault) RecallFacts added in v0.5.0 

func (v *Vault) RecallFacts(req RecallRequest) (RecallResult, error)

func (*Vault) ReinforceBelief 

func (v *Vault) ReinforceBelief(relPath, source string) error

ReinforceBelief boosts the confidence of a belief file. Independent source: +0.05, same source: +0.02. Capped at 1.0.

func (*Vault) ReinforceFact 

func (v *Vault) ReinforceFact(relPath string) error

ReinforceFact increases a fact's confidence and stability after a successful recall. This is the FSRS "review" operation — accessing a fact proves it's still relevant, so stability grows and confidence resets toward 1.0.

func (*Vault) RejectPR 

func (v *Vault) RejectPR(relPath, closedBy, reason string) error

RejectPR marks a PR as rejected and weakens all linked beliefs.

func (*Vault) RemoveDependency 

func (v *Vault) RemoveDependency(missionSlug, depSlug string) error

RemoveDependency removes a dependency from a mission. 

func (v *Vault) ResolveWikiLink(link string) string

ResolveWikiLink finds the .md file matching a [[wiki-link]].

func (*Vault) SaveTuneReport added in v0.5.0 

func (v *Vault) SaveTuneReport(report *FSRSTuneReport) (string, error)

SaveTuneReport writes a versioned tuning report to memory/fsrs-tuning/. Reports are never overwritten — each analysis gets its own timestamped file.

func (*Vault) Search 

func (v *Vault) Search(query string, limit int) ([]index.SearchResult, error)

Search performs full-text search across the index. Returns empty results if no index is loaded.

func (*Vault) SearchFacts 

func (v *Vault) SearchFacts(query string, limit int) ([]string, error)

SearchFacts searches memory facts via FTS, filtering to memory/facts/ paths. Falls back to listing all facts if no index is loaded.

func (*Vault) SearchFactsWithOptions added in v0.5.0 

func (v *Vault) SearchFactsWithOptions(query string, limit int, opts FactSearchOptions) ([]string, error)

func (*Vault) SearchTraces added in v0.5.0 

func (v *Vault) SearchTraces(query string, limit int) ([]*markdown.Document, error)

SearchTraces searches memory/traces/ for traces matching the query. Uses the index if available, falls back to substring matching.

func (*Vault) SetTrustStage 

func (v *Vault) SetTrustStage(stage int, updatedBy, reason string) error

SetTrustStage updates the trust stage. Only the operator should call this — MODUS never self-promotes. Appends a transition record to the history in the body.

func (*Vault) ShipClock 

func (v *Vault) ShipClock() (map[string]interface{}, error)

ShipClock returns the countdown to target.

func (*Vault) ShipClockJSON 

func (v *Vault) ShipClockJSON() (string, error)

ShipClockJSON returns ShipClock as formatted JSON.

func (*Vault) Status 

func (v *Vault) Status() map[string]interface{}

Status returns vault-wide statistics.

func (*Vault) StatusJSON 

func (v *Vault) StatusJSON() (string, error)

StatusJSON returns Status() as formatted JSON.

func (*Vault) StoreCorrection added in v0.5.0 

func (v *Vault) StoreCorrection(original, corrected, context, createdBy string) (string, error)

StoreCorrection writes a correction pattern to memory/corrections/. Corrections are search-time annotations — they never rewrite canonical facts. The original phrasing is matched against future queries to surface the corrected version.

func (*Vault) StoreEpisodeGoverned added in v0.5.0 

func (v *Vault) StoreEpisodeGoverned(body string, auth EpisodeWriteAuthority) (string, string, error)

StoreEpisodeGoverned writes a first-class episodic memory object. Episodes are append-only raw or near-raw traces that later semantic memory can cite by source_event_id and lineage_id.

func (*Vault) StoreFact 

func (v *Vault) StoreFact(subject, predicate, value string, confidence float64, importance string) (string, error)

StoreFact writes a new memory fact as a .md file.

func (*Vault) StoreFactGoverned added in v0.5.0 

func (v *Vault) StoreFactGoverned(subject, predicate, value string, confidence float64, importance string, auth FactWriteAuthority) (string, error)

StoreFactGoverned writes a canonical fact only after the trust gate has classified the declared authority and, when permitted, records the decision in the ledger.

func (*Vault) StoreTrace added in v0.5.0 

func (v *Vault) StoreTrace(task, outcome string, steps []string, durationSec float64, toolsUsed []string, createdBy, model string) (string, error)

StoreTrace writes a task execution trace to memory/traces/. Traces are provenance-rich procedural memory — they record what was tried, what worked, and what failed, with full attribution.

func (*Vault) TouchFact 

func (v *Vault) TouchFact(relPath string) error

TouchFact updates last_accessed on a fact, resetting its decay clock.

func (*Vault) WeakenBelief 

func (v *Vault) WeakenBelief(relPath string) error

WeakenBelief reduces the confidence of a belief by 0.10, with a floor of 0.05.

func (*Vault) Write 

func (v *Vault) Write(relPath string, fm map[string]interface{}, body string) error

Write creates or overwrites a markdown file with frontmatter + body.

type WikiLinkAudit added in v0.5.0 

type WikiLinkAudit struct {
	Documents   int
	Links       int
	Rewrites    []WikiLinkRewrite
	Issues      []WikiLinkIssue
	UpdatedDocs int
}

type WikiLinkIssue added in v0.5.0 

type WikiLinkIssue struct {
	SourcePath string
	Raw        string
	Target     string
	Reason     string
}

type WikiLinkRewrite added in v0.5.0 

type WikiLinkRewrite struct {
	SourcePath string
	Before     string
	After      string
}

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.