schema

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Mar 22, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package schema defines the core data structures for the memory substrate as specified in RFC 15A (Schema Appendix).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsValidMemoryType added in v0.1.5 

func IsValidMemoryType(mt MemoryType) bool

IsValidMemoryType reports whether mt is one of the allowed memory types.

func IsValidOutcomeStatus added in v0.1.5 

func IsValidOutcomeStatus(s OutcomeStatus) bool

IsValidOutcomeStatus reports whether s is one of the allowed outcome statuses.

func IsValidSensitivity added in v0.1.3 

func IsValidSensitivity(s Sensitivity) bool

IsValidSensitivity reports whether s is one of the allowed sensitivity values.

func IsValidTaskState added in v0.1.5 

func IsValidTaskState(s TaskState) bool

IsValidTaskState reports whether s is one of the allowed task states.

Types

type AuditAction 

type AuditAction string

AuditAction defines the type of action recorded in an audit entry. RFC 15A.8: Every revision MUST be auditable and traceable to evidence. 

const (
	// AuditActionCreate indicates a new record was created.
	AuditActionCreate AuditAction = "create"

	// AuditActionRevise indicates an existing record was revised.
	AuditActionRevise AuditAction = "revise"

	// AuditActionFork indicates a record was forked into conditional variants.
	AuditActionFork AuditAction = "fork"

	// AuditActionMerge indicates records were merged together.
	AuditActionMerge AuditAction = "merge"

	// AuditActionDelete indicates a record was deleted.
	AuditActionDelete AuditAction = "delete"

	// AuditActionReinforce indicates a record's salience was reinforced.
	AuditActionReinforce AuditAction = "reinforce"

	// AuditActionDecay indicates a record's salience was decayed.
	AuditActionDecay AuditAction = "decay"
)

type AuditEntry 

type AuditEntry struct {
	// Action is the type of action that was performed.
	// RFC 15A.8: Required field (create, revise, fork, merge, delete, reinforce, decay).
	Action AuditAction `json:"action"`

	// Actor identifies who or what performed the action.
	// RFC 15A.8: Required field (e.g., user ID, system component, consolidator).
	Actor string `json:"actor"`

	// Timestamp records when the action occurred.
	// RFC 15A.8: Required field.
	Timestamp time.Time `json:"timestamp"`

	// Rationale explains why the action was taken.
	// RFC 15A.8: Required field for traceability.
	Rationale string `json:"rationale"`
}

AuditEntry records a single action in a memory record's audit log. RFC 15A.8: Every revision MUST be auditable and traceable to evidence.

type CompetencePayload 

type CompetencePayload struct {
	// Kind identifies this as a competence payload.
	// RFC 15A.9: Required field with const value "competence".
	Kind string `json:"kind"`

	// SkillName is the name of the skill or procedure.
	// RFC 15A.9: Required field.
	SkillName string `json:"skill_name"`

	// Triggers define when this competence applies.
	// RFC 15A.9: Required field.
	Triggers []Trigger `json:"triggers"`

	// Recipe contains the ordered or conditional steps.
	// RFC 15A.9: Required field.
	Recipe []RecipeStep `json:"recipe"`

	// RequiredTools lists tools needed for this competence.
	// RFC 15A.5: Optional array of tool references.
	RequiredTools []string `json:"required_tools,omitempty"`

	// FailureModes documents known failure cases.
	// RFC 15A.9: Optional array of failure descriptions.
	FailureModes []string `json:"failure_modes,omitempty"`

	// Fallbacks provides alternative steps when primary recipe fails.
	// RFC 15A.9: Optional array of fallback strategies.
	Fallbacks []string `json:"fallbacks,omitempty"`

	// Performance tracks success and failure statistics.
	// RFC 15A.5: Performance stats for competence selection.
	Performance *PerformanceStats `json:"performance,omitempty"`

	// Version is the version identifier for this competence.
	// RFC 15A.9: Optional version tracking.
	Version string `json:"version,omitempty"`
}

CompetencePayload encodes procedural knowledge: how to achieve goals. RFC 15A.9: Competence payloads represent "knowing how" rather than "knowing that".

func (CompetencePayload) PayloadKind 

func (CompetencePayload) PayloadKind() string

type Constraint 

type Constraint struct {
	// Type identifies the kind of constraint.
	Type string `json:"type"`

	// Key is the constraint key or name.
	Key string `json:"key"`

	// Value is the constraint value.
	Value any `json:"value"`

	// Required indicates if the constraint is mandatory.
	Required bool `json:"required,omitempty"`
}

Constraint represents a constraint on task execution. RFC 15A.3, 15A.6: Constraints affect plan selection and execution.

type DecayCurve 

type DecayCurve string

DecayCurve defines the mathematical function used for salience decay. RFC 15A.3, 15A.7: Decay curves control how salience decreases over time. 

const (
	// DecayCurveExponential uses exponential decay with a half-life parameter.
	DecayCurveExponential DecayCurve = "exponential"
)

type DecayProfile 

type DecayProfile struct {
	// Curve specifies the mathematical function for decay.
	// RFC 15A.3: Required field. The current implementation supports exponential decay only.
	Curve DecayCurve `json:"curve"`

	// HalfLifeSeconds defines the time for salience to decay by half.
	// RFC 15A.3: Required field with minimum value of 1.
	HalfLifeSeconds int64 `json:"half_life_seconds"`

	// MinSalience is the floor value below which salience cannot decay.
	// RFC 15A.7: Corresponds to the "floor" field in DecayProfile.
	// Value range: [0, 1]
	MinSalience float64 `json:"min_salience,omitempty"`

	// MaxAgeSeconds is the maximum age before the record is eligible for deletion.
	// Optional field that can trigger deletion regardless of salience.
	MaxAgeSeconds int64 `json:"max_age_seconds,omitempty"`

	// ReinforcementGain defines how much salience increases on reinforcement.
	// RFC 15A.7: Decay is reversible via reinforcement.
	ReinforcementGain float64 `json:"reinforcement_gain,omitempty"`
}

DecayProfile defines how salience decreases over time. RFC 15A.7: Decay profiles MUST be monotonic and reversible via reinforcement.

type DeletionPolicy 

type DeletionPolicy string

DeletionPolicy defines how memory records may be deleted. RFC 15A.3: Controls whether records can be automatically pruned. 

const (
	// DeletionPolicyAutoPrune allows automatic deletion when salience drops
	// below threshold.
	DeletionPolicyAutoPrune DeletionPolicy = "auto_prune"

	// DeletionPolicyManualOnly requires explicit user action for deletion.
	DeletionPolicyManualOnly DeletionPolicy = "manual_only"

	// DeletionPolicyNever prevents deletion entirely.
	DeletionPolicyNever DeletionPolicy = "never"
)

type EdgeKind 

type EdgeKind string

EdgeKind defines the type of edge in a plan graph. RFC 15A.10: Plan graph edges represent dependencies. 

const (
	// EdgeKindData indicates a data dependency edge.
	EdgeKindData EdgeKind = "data"

	// EdgeKindControl indicates a control flow edge.
	EdgeKindControl EdgeKind = "control"
)

type EnvironmentSnapshot 

type EnvironmentSnapshot struct {
	// OS is the operating system identifier.
	OS string `json:"os,omitempty"`

	// OSVersion is the operating system version.
	OSVersion string `json:"os_version,omitempty"`

	// ToolVersions maps tool names to their versions.
	ToolVersions map[string]string `json:"tool_versions,omitempty"`

	// WorkingDirectory is the current working directory.
	WorkingDirectory string `json:"working_directory,omitempty"`

	// Context contains additional contextual information.
	Context map[string]any `json:"context,omitempty"`
}

EnvironmentSnapshot captures the environment state during an episode. RFC 15A.2: Includes OS, versions, context.

type EpisodicPayload 

type EpisodicPayload struct {
	// Kind identifies this as an episodic payload.
	// RFC 15A.6: Required field with const value "episodic".
	Kind string `json:"kind"`

	// Timeline is a time-ordered sequence of events.
	// RFC 15A.6: Required field.
	Timeline []TimelineEvent `json:"timeline"`

	// ToolGraph captures tool calls and data flow during the episode.
	// RFC 15A.2: Extension for detailed tool tracking.
	ToolGraph []ToolNode `json:"tool_graph,omitempty"`

	// Environment captures the environment snapshot during the episode.
	// RFC 15A.2: OS, versions, context.
	Environment *EnvironmentSnapshot `json:"environment,omitempty"`

	// Outcome indicates the result of the episode.
	// RFC 15A.2: success | failure | partial.
	Outcome OutcomeStatus `json:"outcome,omitempty"`

	// Artifacts references external artifacts (logs, screenshots, files).
	// RFC 15A.6: Optional array of artifact references.
	Artifacts []string `json:"artifacts,omitempty"`

	// ToolGraphRef is an optional reference to an external tool graph.
	// RFC 15A.6: Optional field for external graph storage.
	ToolGraphRef string `json:"tool_graph_ref,omitempty"`
}

EpisodicPayload captures raw experience as a time-ordered sequence of events. RFC 15A.6: Episodic payloads MUST be append-only. Semantic correction is forbidden.

func (EpisodicPayload) PayloadKind 

func (EpisodicPayload) PayloadKind() string

type Lifecycle 

type Lifecycle struct {
	// Decay defines the decay profile for this record's salience.
	Decay DecayProfile `json:"decay"`

	// LastReinforcedAt is the timestamp when salience was last reinforced.
	// RFC 15A.3: Required field for lifecycle tracking.
	LastReinforcedAt time.Time `json:"last_reinforced_at"`

	// Pinned indicates whether the record is protected from decay.
	// When true, salience will not decrease over time.
	Pinned bool `json:"pinned,omitempty"`

	// DeletionPolicy controls how this record may be deleted.
	// RFC 15A.3: Determines auto-prune, manual-only, or never deletion.
	DeletionPolicy DeletionPolicy `json:"deletion_policy,omitempty"`
}

Lifecycle contains lifecycle metadata for a memory record. RFC 15A.3: Lifecycle controls decay, reinforcement, and deletion behavior.

type MemoryRecord 

type MemoryRecord struct {
	// ID is a globally unique identifier (UUID recommended).
	// RFC 15A.2: Required field, immutable once created.
	ID string `json:"id"`

	// Type declares the memory type (episodic, working, semantic, competence, plan_graph).
	// RFC 15A.2: Required field.
	Type MemoryType `json:"type"`

	// Sensitivity is the sensitivity classification for access control.
	// RFC 15A.2: Required field (public, low, medium, high, hyper).
	Sensitivity Sensitivity `json:"sensitivity"`

	// Confidence is the epistemic confidence in this record.
	// RFC 15A.2: Required field with range [0, 1].
	Confidence float64 `json:"confidence"`

	// Salience is the decay-weighted importance score.
	// RFC 15A.2: Required field with range [0, +inf).
	// Note: JSON schema shows max 1, but conceptual model allows unbounded salience.
	Salience float64 `json:"salience"`

	// Scope defines the visibility scope (implementation-defined).
	// RFC 15A.2: Optional field. Examples: user, device, project, workspace, global.
	Scope string `json:"scope,omitempty"`

	// Tags are free-form labels for categorization and retrieval.
	// RFC 15A.2: Optional array of strings.
	Tags []string `json:"tags,omitempty"`

	// CreatedAt is the timestamp when this record was created.
	// RFC 15A.2: Required field.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is the timestamp when this record was last updated.
	// RFC 15A.2: Required field.
	UpdatedAt time.Time `json:"updated_at"`

	// Lifecycle contains decay, reinforcement, and deletion metadata.
	// RFC 15A.2: Required field.
	Lifecycle Lifecycle `json:"lifecycle"`

	// Provenance links this record to its source events or artifacts.
	// RFC 15A.2: Required field.
	Provenance Provenance `json:"provenance"`

	// Relations are graph edges to other MemoryRecords.
	// RFC 15A.2: Optional array of relations.
	Relations []Relation `json:"relations,omitempty"`

	// Payload is the type-specific structured content.
	// RFC 15A.2: Required field, one of the five payload types.
	Payload Payload `json:"payload"`

	// AuditLog tracks all actions performed on this record.
	// RFC 15A.8: Required for auditability.
	AuditLog []AuditEntry `json:"audit_log"`
}

MemoryRecord is the atomic unit of storage in the memory substrate. RFC 15A.2, 15A.1: Every stored memory item MUST conform to the MemoryRecord shape.

This is the base record type that MUST NOT be bypassed by any memory type. All memory records share this common structure with type-specific payloads.

func NewMemoryRecord 

func NewMemoryRecord(id string, memType MemoryType, sensitivity Sensitivity, payload Payload) *MemoryRecord

NewMemoryRecord creates a new MemoryRecord with required fields initialized. This is a convenience constructor that sets timestamps and creates empty slices.

func (MemoryRecord) MarshalJSON 

func (mr MemoryRecord) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for MemoryRecord.

func (*MemoryRecord) UnmarshalJSON 

func (mr *MemoryRecord) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for MemoryRecord.

func (*MemoryRecord) Validate 

func (mr *MemoryRecord) Validate() error

Validate performs basic validation on the MemoryRecord. Returns an error if required fields are missing or invalid.

type MemoryType 

type MemoryType string

MemoryType defines the category of memory record. RFC 15A.1: MemoryType MUST be one of the defined values. 

const (
	// MemoryTypeEpisodic captures raw experience such as user inputs, tool calls,
	// errors, and observations. Episodic memory is intentionally short-lived and
	// provides evidence for later learning.
	MemoryTypeEpisodic MemoryType = "episodic"

	// MemoryTypeWorking captures the current state of an ongoing task, enabling
	// resumption across sessions or devices.
	MemoryTypeWorking MemoryType = "working"

	// MemoryTypeSemantic stores stable knowledge such as preferences, environment
	// facts, and relationships. Semantic memory supports revisability.
	MemoryTypeSemantic MemoryType = "semantic"

	// MemoryTypeCompetence encodes procedural knowledge: how to achieve goals
	// reliably under specific conditions.
	MemoryTypeCompetence MemoryType = "competence"

	// MemoryTypePlanGraph stores reusable solution structures as directed graphs
	// of actions.
	MemoryTypePlanGraph MemoryType = "plan_graph"
)

type OutcomeStatus 

type OutcomeStatus string

OutcomeStatus defines the result of an episodic experience. RFC 15A.6: Episodic records track outcome status. 

const (
	// OutcomeStatusSuccess indicates the experience completed successfully.
	OutcomeStatusSuccess OutcomeStatus = "success"

	// OutcomeStatusFailure indicates the experience ended in failure.
	OutcomeStatusFailure OutcomeStatus = "failure"

	// OutcomeStatusPartial indicates partial success or incomplete outcome.
	OutcomeStatusPartial OutcomeStatus = "partial"
)

type Payload 

type Payload interface {
	// PayloadKind returns the kind identifier for this payload type.
	// This corresponds to the "kind" field in each payload schema.
	PayloadKind() string
	// contains filtered or unexported methods
}

Payload is the interface that all memory payload types must implement. RFC 15A.2: Payload is a oneOf of the five payload types.

type PayloadWrapper 

type PayloadWrapper struct {
	Payload Payload
}

PayloadWrapper is used for JSON marshaling/unmarshaling of the Payload interface.

func (PayloadWrapper) MarshalJSON 

func (pw PayloadWrapper) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for PayloadWrapper.

func (*PayloadWrapper) UnmarshalJSON 

func (pw *PayloadWrapper) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for PayloadWrapper. It uses the "kind" field to determine the concrete payload type.

type PerformanceStats 

type PerformanceStats struct {
	// SuccessCount is the number of successful uses.
	SuccessCount int64 `json:"success_count,omitempty"`

	// FailureCount is the number of failed uses.
	FailureCount int64 `json:"failure_count,omitempty"`

	// SuccessRate is the computed success rate.
	// Value range: [0, 1]
	SuccessRate float64 `json:"success_rate,omitempty"`

	// AvgLatencyMs is the average execution time in milliseconds.
	AvgLatencyMs float64 `json:"avg_latency_ms,omitempty"`

	// LastUsedAt is when this was last used.
	LastUsedAt *time.Time `json:"last_used_at,omitempty"`
}

PerformanceStats tracks success and failure statistics. RFC 15A.5, 15A.6: Used for competence and plan selection.

type PlanEdge 

type PlanEdge struct {
	// From is the source node ID.
	// RFC 15A.10: Required field.
	From string `json:"from"`

	// To is the target node ID.
	// RFC 15A.10: Required field.
	To string `json:"to"`

	// Kind specifies the edge type (data or control).
	// RFC 15A.10: Required field.
	Kind EdgeKind `json:"kind"`
}

PlanEdge represents a dependency edge in a plan graph. RFC 15A.10: Edges connect nodes with data or control dependencies.

type PlanGraphPayload 

type PlanGraphPayload struct {
	// Kind identifies this as a plan_graph payload.
	// RFC 15A.10: Required field with const value "plan_graph".
	Kind string `json:"kind"`

	// PlanID is the unique identifier for this plan.
	// RFC 15A.10: Required field.
	PlanID string `json:"plan_id"`

	// Version is the version identifier for this plan.
	// RFC 15A.10: Required field.
	Version string `json:"version"`

	// Intent is the high-level intent label (e.g., setup_project).
	// RFC 15A.10: Optional field for intent matching.
	Intent string `json:"intent,omitempty"`

	// Constraints define trust requirements, sensitivity limits, etc.
	// RFC 15A.10: Optional constraint object.
	Constraints map[string]any `json:"constraints,omitempty"`

	// InputsSchema defines the expected inputs for the plan.
	// RFC 15A.10: Optional schema definition.
	InputsSchema map[string]any `json:"inputs_schema,omitempty"`

	// OutputsSchema defines the expected outputs from the plan.
	// RFC 15A.10: Optional schema definition.
	OutputsSchema map[string]any `json:"outputs_schema,omitempty"`

	// Nodes are the action nodes in the plan graph.
	// RFC 15A.10: Required field.
	Nodes []PlanNode `json:"nodes"`

	// Edges are the dependency edges in the plan graph.
	// RFC 15A.10: Required field.
	Edges []PlanEdge `json:"edges"`

	// Metrics track plan execution statistics.
	// RFC 15A.10: Optional performance metrics.
	Metrics *PlanMetrics `json:"metrics,omitempty"`
}

PlanGraphPayload stores reusable solution structures as directed graphs. RFC 15A.10: Plan graphs MUST be reusable, versioned, and selectable by constraint matching.

func (PlanGraphPayload) PayloadKind 

func (PlanGraphPayload) PayloadKind() string

type PlanMetrics 

type PlanMetrics struct {
	// AvgLatencyMs is the average execution time in milliseconds.
	AvgLatencyMs float64 `json:"avg_latency_ms,omitempty"`

	// FailureRate is the rate of failed executions.
	// Value range: [0, 1]
	FailureRate float64 `json:"failure_rate,omitempty"`

	// ExecutionCount is the total number of executions.
	ExecutionCount int64 `json:"execution_count,omitempty"`

	// LastExecutedAt is when this plan was last executed.
	LastExecutedAt *time.Time `json:"last_executed_at,omitempty"`
}

PlanMetrics tracks execution statistics for a plan. RFC 15A.10: Includes latency and failure rate metrics.

type PlanNode 

type PlanNode struct {
	// ID is the unique identifier for this node within the plan.
	// RFC 15A.10: Required field.
	ID string `json:"id"`

	// Op is the action or tool identifier.
	// RFC 15A.10: Required field.
	Op string `json:"op"`

	// Params contains parameters for the operation.
	// RFC 15A.10: Optional parameter object.
	Params map[string]any `json:"params,omitempty"`

	// Guards define conditional execution criteria.
	// RFC 15A.10: Optional guards for conditional execution.
	Guards map[string]any `json:"guards,omitempty"`
}

PlanNode represents an action node in a plan graph. RFC 15A.10: Nodes have ID, operation, params, and guards.

type Provenance 

type Provenance struct {
	// Sources is the list of provenance sources that justify this record.
	// RFC 15A.4: Required field containing at least one source.
	Sources []ProvenanceSource `json:"sources"`

	// CreatedBy identifies what created this record (e.g., classifier/policy/consolidator version).
	// RFC 15A.4: Optional field for tracking creation origin.
	CreatedBy string `json:"created_by,omitempty"`
}

Provenance tracks the sources and origins of a memory record. RFC 15A.4: Provenance links connect memory to source events or artifacts.

type ProvenanceKind 

type ProvenanceKind string

ProvenanceKind defines the type of source in provenance tracking. RFC 15A.4: Provenance links connect memory to source events or artifacts. 

const (
	// ProvenanceKindEvent indicates the source is an event.
	ProvenanceKindEvent ProvenanceKind = "event"

	// ProvenanceKindArtifact indicates the source is an artifact (log, file, etc.).
	ProvenanceKindArtifact ProvenanceKind = "artifact"

	// ProvenanceKindToolCall indicates the source is a tool invocation.
	ProvenanceKindToolCall ProvenanceKind = "tool_call"

	// ProvenanceKindObservation indicates the source is an observation.
	ProvenanceKindObservation ProvenanceKind = "observation"

	// ProvenanceKindOutcome indicates the source is a task outcome.
	ProvenanceKindOutcome ProvenanceKind = "outcome"
)

type ProvenanceRef 

type ProvenanceRef struct {
	// SourceType identifies the type of source (event, tool, observation, human).
	// RFC 15A.8: Required field.
	SourceType string `json:"source_type"`

	// SourceID is the unique identifier for the source.
	// RFC 15A.8: Required field.
	SourceID string `json:"source_id"`

	// Timestamp records when this evidence was created.
	// RFC 15A.8: Required field.
	Timestamp time.Time `json:"timestamp"`
}

ProvenanceRef is a reference to evidence supporting a memory record. RFC 15A.8: Used for linking semantic payloads to their evidence.

type ProvenanceSource 

type ProvenanceSource struct {
	// Kind specifies the type of source (event, artifact, tool_call, observation, outcome).
	// RFC 15A.4: Required field.
	Kind ProvenanceKind `json:"kind"`

	// Ref is an opaque reference into the host system.
	// RFC 15A.4: Required field.
	Ref string `json:"ref"`

	// Hash is an optional content hash for immutability verification.
	// RFC 15A.4: Optional field for content-addressed artifacts.
	Hash string `json:"hash,omitempty"`

	// CreatedBy identifies the actor or system that created this source.
	// Extension field for detailed provenance tracking.
	CreatedBy string `json:"created_by,omitempty"`

	// Timestamp records when this source was created or observed.
	// RFC 15A.8: Provenance references include timestamps.
	Timestamp time.Time `json:"timestamp,omitempty"`
}

ProvenanceSource represents a single source of evidence for a memory record. RFC 15A.4: Each source has a kind, reference, and optional hash.

type RecipeStep 

type RecipeStep struct {
	// Step is the human-readable step description.
	// RFC 15A.9: Required field.
	Step string `json:"step"`

	// Tool is the tool to use for this step.
	// RFC 15A.9: Optional field.
	Tool string `json:"tool,omitempty"`

	// ArgsSchema defines the expected arguments for the tool.
	// RFC 15A.9: Optional schema definition.
	ArgsSchema map[string]any `json:"args_schema,omitempty"`

	// Validation describes how to verify step success.
	// RFC 15A.9: Optional validation criteria.
	Validation string `json:"validation,omitempty"`
}

RecipeStep represents a single step in a competence procedure. RFC 15A.9: Steps have a description, optional tool, and validation.

type Relation 

type Relation struct {
	// Predicate describes the relationship type.
	// RFC 15A.5: Required field. Examples: supports, contradicts, derived_from, supersedes.
	Predicate string `json:"predicate"`

	// TargetID is the ID of the related memory record.
	// RFC 15A.5: Required field.
	TargetID string `json:"target_id"`

	// Weight indicates the strength of the relationship.
	// RFC 15A.5: Optional field with range [0, 1].
	Weight float64 `json:"weight,omitempty"`

	// CreatedAt records when this relation was established.
	// Extension field for tracking relation history.
	CreatedAt time.Time `json:"created_at,omitempty"`
}

Relation represents a relationship between memory records. RFC 15A.5: Relations form graph edges between MemoryRecords.

type RevisionState 

type RevisionState struct {
	// Supersedes is the ID of the record this supersedes.
	// RFC 15A.8: Optional field.
	Supersedes string `json:"supersedes,omitempty"`

	// SupersededBy is the ID of the record that supersedes this.
	// RFC 15A.8: Optional field.
	SupersededBy string `json:"superseded_by,omitempty"`

	// Status is the current revision status.
	// RFC 15A.8: Optional field (active, contested, retracted).
	Status RevisionStatus `json:"status,omitempty"`
}

RevisionState tracks the revision status of a semantic fact. RFC 15A.8: Supports supersedes relationships and status tracking.

type RevisionStatus 

type RevisionStatus string

RevisionStatus indicates the current state of a semantic memory revision. RFC 15A.8: Semantic records support revision, replacement, conditionality. 

const (
	// RevisionStatusActive indicates the record is currently valid.
	RevisionStatusActive RevisionStatus = "active"

	// RevisionStatusContested indicates uncertainty until resolved.
	RevisionStatusContested RevisionStatus = "contested"

	// RevisionStatusRetracted indicates the record has been withdrawn.
	RevisionStatusRetracted RevisionStatus = "retracted"
)

type SemanticPayload 

type SemanticPayload struct {
	// Kind identifies this as a semantic payload.
	// RFC 15A.8: Required field with const value "semantic".
	Kind string `json:"kind"`

	// Subject is the entity the fact is about.
	// RFC 15A.8: Required field.
	Subject string `json:"subject"`

	// Predicate is the relationship or property.
	// RFC 15A.8: Required field.
	Predicate string `json:"predicate"`

	// Object is the value or related entity.
	// RFC 15A.8: Required field. Can be string, number, boolean, object, or array.
	Object any `json:"object"`

	// Validity defines when this fact is valid.
	// RFC 15A.8: Required field.
	Validity Validity `json:"validity"`

	// Evidence links to provenance supporting this fact.
	// RFC 15A.4: Optional array of evidence references.
	Evidence []ProvenanceRef `json:"evidence,omitempty"`

	// RevisionPolicy defines how this fact should be revised.
	// RFC 15A.4: replace | fork | contest.
	RevisionPolicy string `json:"revision_policy,omitempty"`

	// Revision tracks revision state for this fact.
	// RFC 15A.8: Optional field for revision tracking.
	Revision *RevisionState `json:"revision,omitempty"`
}

SemanticPayload stores revisable facts as subject-predicate-object triples. RFC 15A.8: Semantic payloads MUST support coexistence of multiple conditional truths.

func (SemanticPayload) PayloadKind 

func (SemanticPayload) PayloadKind() string

type Sensitivity 

type Sensitivity string

Sensitivity defines the sensitivity classification for memory records. RFC 15A.1: Sensitivity MUST be one of the defined values. Higher sensitivity levels require stricter trust context for retrieval. 

const (
	// SensitivityPublic indicates content that can be freely shared.
	SensitivityPublic Sensitivity = "public"

	// SensitivityLow indicates content with minimal sensitivity.
	SensitivityLow Sensitivity = "low"

	// SensitivityMedium indicates moderately sensitive content.
	SensitivityMedium Sensitivity = "medium"

	// SensitivityHigh indicates highly sensitive content requiring elevated trust.
	SensitivityHigh Sensitivity = "high"

	// SensitivityHyper indicates extremely sensitive content with maximum protection.
	SensitivityHyper Sensitivity = "hyper"
)

type TaskState 

type TaskState string

TaskState defines the current state of a working memory task. RFC 15A.7: Working memory tracks task state for resumption. 

const (
	// TaskStatePlanning indicates the task is in planning phase.
	TaskStatePlanning TaskState = "planning"

	// TaskStateExecuting indicates the task is actively being executed.
	TaskStateExecuting TaskState = "executing"

	// TaskStateBlocked indicates the task cannot proceed due to a blocker.
	TaskStateBlocked TaskState = "blocked"

	// TaskStateWaiting indicates the task is waiting for external input.
	TaskStateWaiting TaskState = "waiting"

	// TaskStateDone indicates the task has completed.
	TaskStateDone TaskState = "done"
)

type TimelineEvent 

type TimelineEvent struct {
	// T is the timestamp of the event.
	// RFC 15A.6: Required field.
	T time.Time `json:"t"`

	// EventKind identifies the type of event.
	// RFC 15A.6: Required field.
	EventKind string `json:"event_kind"`

	// Ref is a reference to the event details.
	// RFC 15A.6: Required field.
	Ref string `json:"ref"`

	// Summary is an optional human-readable summary.
	// RFC 15A.6: Optional field.
	Summary string `json:"summary,omitempty"`
}

TimelineEvent represents a single event in an episodic timeline. RFC 15A.6: Events have timestamp, kind, reference, and optional summary.

type ToolNode 

type ToolNode struct {
	// ID is the unique identifier for this tool node.
	ID string `json:"id"`

	// Tool is the name or identifier of the tool.
	Tool string `json:"tool"`

	// Args contains the arguments passed to the tool.
	Args map[string]any `json:"args,omitempty"`

	// Result contains the output from the tool.
	Result any `json:"result,omitempty"`

	// Timestamp records when the tool was invoked.
	Timestamp time.Time `json:"timestamp,omitempty"`

	// DependsOn lists IDs of tool nodes this depends on.
	DependsOn []string `json:"depends_on,omitempty"`
}

ToolNode represents a tool call in the tool graph. RFC 15A.2: Tool graph captures tool calls and data flow.

type Trigger 

type Trigger struct {
	// Signal is the trigger signal (e.g., error signature, intent label).
	// RFC 15A.9: Required field.
	Signal string `json:"signal"`

	// Conditions are additional matching conditions.
	// RFC 15A.9: Optional field with implementation-defined keys.
	Conditions map[string]any `json:"conditions,omitempty"`
}

Trigger defines when a competence should be activated. RFC 15A.9: Triggers have a signal and optional conditions.

type ValidationError 

type ValidationError struct {
	Field   string
	Message string
}

ValidationError represents a validation failure for a specific field.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

type Validity 

type Validity struct {
	// Mode specifies the validity mode.
	// RFC 15A.8: Required field (global, conditional, timeboxed).
	Mode ValidityMode `json:"mode"`

	// Conditions contains implementation-defined conditional keys.
	// RFC 15A.8: Optional field for conditional validity.
	Conditions map[string]any `json:"conditions,omitempty"`

	// Start is the start of the validity window for timeboxed validity.
	// RFC 15A.8: Optional field for timeboxed mode.
	Start *time.Time `json:"start,omitempty"`

	// End is the end of the validity window for timeboxed validity.
	// RFC 15A.8: Optional field for timeboxed mode.
	End *time.Time `json:"end,omitempty"`
}

Validity defines when a semantic fact is valid. RFC 15A.8: Supports global, conditional, and timeboxed validity.

type ValidityMode 

type ValidityMode string

ValidityMode defines how a semantic fact's validity is scoped. RFC 15A.8: Semantic records support conditional validity. 

const (
	// ValidityModeGlobal indicates the fact is universally valid.
	ValidityModeGlobal ValidityMode = "global"

	// ValidityModeConditional indicates the fact is valid under specific conditions.
	ValidityModeConditional ValidityMode = "conditional"

	// ValidityModeTimeboxed indicates the fact is valid within a time window.
	ValidityModeTimeboxed ValidityMode = "timeboxed"
)

type WorkingPayload 

type WorkingPayload struct {
	// Kind identifies this as a working payload.
	// RFC 15A.7: Required field with const value "working".
	Kind string `json:"kind"`

	// ThreadID is the identifier for the current thread/session.
	// RFC 15A.7: Required field.
	ThreadID string `json:"thread_id"`

	// State indicates the current task state.
	// RFC 15A.7: Required field (planning, executing, blocked, waiting, done).
	State TaskState `json:"state"`

	// ActiveConstraints lists constraints currently active for the task.
	// RFC 15A.3: Working memory tracks active constraints.
	ActiveConstraints []Constraint `json:"active_constraints,omitempty"`

	// NextActions lists the next planned actions.
	// RFC 15A.7: Optional array of action hints.
	NextActions []string `json:"next_actions,omitempty"`

	// OpenQuestions lists unresolved questions for the task.
	// RFC 15A.7: Optional array of questions.
	OpenQuestions []string `json:"open_questions,omitempty"`

	// ContextSummary provides a summary of the current context.
	// RFC 15A.7: Optional field for context tracking.
	ContextSummary string `json:"context_summary,omitempty"`
}

WorkingPayload captures the current state of an ongoing task. RFC 15A.7: Working memory MAY be freely edited and discarded when the task ends.

func (WorkingPayload) PayloadKind 

func (WorkingPayload) PayloadKind() 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.