memoryflow

package
v2.17.0 Latest Latest
Warning

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

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

Documentation

Overview

Package memoryflow provides a higher-level workflow facade on top of CortexDB's memory, knowledge, and brain primitives.

The package is intended for applications that want "memory system" behavior rather than direct database primitives. It focuses on:

  • transcript ingest as episodic memory exchanges
  • deterministic taxonomy and project conventions
  • layered wake-up context assembly
  • session-close promotion into durable knowledge
  • diary and reply-protocol helpers

LLM-dependent behavior is exposed through interfaces:

  • QueryPlanner
  • SessionExtractor
  • PromotionPolicy

This keeps the package usable in fully deterministic mode while allowing applications to plug in planner and extraction logic when needed.

Index

Constants

View Source 
const DefaultConfigFilename = ".cortexdb-memoryflow.json"

DefaultConfigFilename is the default project-local memoryflow config file.

Variables

This section is empty.

Functions

func DefaultConfigPath 

func DefaultConfigPath(projectRoot string) string

DefaultConfigPath returns the default config path for a project root.

func SaveConfig 

func SaveConfig(path string, cfg ProjectConfig) error

SaveConfig writes a project config to disk.

Types

type CloseSessionRequest 

type CloseSessionRequest struct {
	Transcript Transcript        `json:"transcript"`
	Scope      string            `json:"scope,omitempty"`
	Namespace  string            `json:"namespace,omitempty"`
	State      SessionState      `json:"state,omitempty"`
	Promote    bool              `json:"promote,omitempty"`
	Collection string            `json:"collection,omitempty"`
	Author     string            `json:"author,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
}

CloseSessionRequest optionally promotes extracted knowledge at session end.

type CloseSessionResponse 

type CloseSessionResponse struct {
	Promotions []cortexdb.KnowledgeRecord `json:"promotions,omitempty"`
	Count      int                        `json:"count"`
}

CloseSessionResponse reports promotions created at session close.

type ConventionRule 

type ConventionRule struct {
	MatchSource      string   `json:"match_source,omitempty"`
	PathContainsAny  []string `json:"path_contains_any,omitempty"`
	TitleContainsAny []string `json:"title_contains_any,omitempty"`
	Wing             string   `json:"wing,omitempty"`
	Room             string   `json:"room,omitempty"`
	Kind             string   `json:"kind,omitempty"`
	AddTags          []string `json:"add_tags,omitempty"`
}

ConventionRule applies deterministic taxonomy defaults when its conditions match.

type ConventionSet 

type ConventionSet struct {
	Project     string           `json:"project,omitempty"`
	DefaultWing string           `json:"default_wing,omitempty"`
	DefaultRoom string           `json:"default_room,omitempty"`
	DefaultKind string           `json:"default_kind,omitempty"`
	Rules       []ConventionRule `json:"rules,omitempty"`
}

ConventionSet is the project-level deterministic taxonomy policy.

func DefaultConventionSet 

func DefaultConventionSet(project string) ConventionSet

DefaultConventionSet returns pragmatic defaults for a project-scoped memory workflow.

type DefaultPromotionPolicy 

type DefaultPromotionPolicy struct{}

DefaultPromotionPolicy keeps high-signal categories and drops generic notes by default.

func (DefaultPromotionPolicy) Select 

func (DefaultPromotionPolicy) Select(_ context.Context, _ Transcript, _ SessionState, candidates []PromotionCandidate) ([]PromotionCandidate, error)

Select filters promotion candidates using a deterministic allowlist.

type DiaryEntryRequest 

type DiaryEntryRequest struct {
	EntryID    string         `json:"entry_id,omitempty"`
	UserID     string         `json:"user_id,omitempty"`
	SessionID  string         `json:"session_id,omitempty"`
	Scope      string         `json:"scope,omitempty"`
	Namespace  string         `json:"namespace,omitempty"`
	Taxonomy   Taxonomy       `json:"taxonomy,omitempty"`
	PathHint   string         `json:"path_hint,omitempty"`
	Content    string         `json:"content"`
	Metadata   map[string]any `json:"metadata,omitempty"`
	Importance float64        `json:"importance,omitempty"`
}

DiaryEntryRequest appends one workflow diary entry.

type DiaryEntryResponse 

type DiaryEntryResponse struct {
	Entry cortexdb.MemoryRecord `json:"entry"`
}

DiaryEntryResponse returns the stored diary memory record.

type DiaryListRequest 

type DiaryListRequest struct {
	UserID    string `json:"user_id,omitempty"`
	SessionID string `json:"session_id,omitempty"`
	Scope     string `json:"scope,omitempty"`
	Namespace string `json:"namespace,omitempty"`
	Limit     int    `json:"limit,omitempty"`
}

DiaryListRequest lists diary entries for a resolved bucket.

type DiaryListResponse 

type DiaryListResponse struct {
	Entries []cortexdb.MemoryRecord `json:"entries"`
}

DiaryListResponse returns chronological diary entries.

type Episode 

type Episode struct {
	Memory        cortexdb.MemoryRecord `json:"memory"`
	ExchangeIndex int                   `json:"exchange_index,omitempty"`
	Taxonomy      Taxonomy              `json:"taxonomy,omitempty"`
	Turns         []TranscriptTurn      `json:"turns,omitempty"`
}

Episode is one stored exchange-shaped memory record plus reconstructed turns.

type GetTranscriptRequest 

type GetTranscriptRequest struct {
	UserID    string `json:"user_id,omitempty"`
	SessionID string `json:"session_id,omitempty"`
	Scope     string `json:"scope,omitempty"`
	Namespace string `json:"namespace,omitempty"`
	Limit     int    `json:"limit,omitempty"`
}

GetTranscriptRequest reconstructs the original transcript for a resolved bucket.

type GetTranscriptResponse 

type GetTranscriptResponse struct {
	Transcript Transcript `json:"transcript"`
	Episodes   []Episode  `json:"episodes"`
}

GetTranscriptResponse returns the reconstructed transcript and its backing episodes.

type HeuristicExtractor 

type HeuristicExtractor struct{}

HeuristicExtractor extracts a small set of durable facts without an LLM.

func (HeuristicExtractor) Extract 

func (HeuristicExtractor) Extract(_ context.Context, transcript Transcript, state SessionState) ([]PromotionCandidate, error)

Extract scans transcript text for simple preference/decision/milestone/problem signals.

type IngestTranscriptRequest 

type IngestTranscriptRequest struct {
	Transcript Transcript     `json:"transcript"`
	Scope      string         `json:"scope,omitempty"`
	Namespace  string         `json:"namespace,omitempty"`
	Wing       string         `json:"wing,omitempty"`
	Room       string         `json:"room,omitempty"`
	Tags       []string       `json:"tags,omitempty"`
	Taxonomy   Taxonomy       `json:"taxonomy,omitempty"`
	Metadata   map[string]any `json:"metadata,omitempty"`
}

IngestTranscriptRequest stores a transcript as episodic memory exchanges.

func (IngestTranscriptRequest) State 

func (req IngestTranscriptRequest) State() SessionState

type IngestTranscriptResponse 

type IngestTranscriptResponse struct {
	MemoryIDs []string `json:"memory_ids"`
	Count     int      `json:"count"`
}

IngestTranscriptResponse summarizes the stored episodic memories.

type ListEpisodesRequest 

type ListEpisodesRequest struct {
	UserID    string `json:"user_id,omitempty"`
	SessionID string `json:"session_id,omitempty"`
	Scope     string `json:"scope,omitempty"`
	Namespace string `json:"namespace,omitempty"`
	Limit     int    `json:"limit,omitempty"`
}

ListEpisodesRequest lists stored episodic memory exchanges for a resolved bucket.

type ListEpisodesResponse 

type ListEpisodesResponse struct {
	Episodes []Episode `json:"episodes"`
}

ListEpisodesResponse returns stored episodic exchange records.

type MCPServerOptions 

type MCPServerOptions struct {
	Implementation *mcp.Implementation
	Instructions   string
	Logger         *slog.Logger
}

MCPServerOptions configures the memoryflow MCP server wrapper.

type Option 

type Option func(*Service)

Option configures the workflow service.

func WithConventions 

func WithConventions(conventions ConventionSet) Option

WithConventions injects deterministic taxonomy conventions.

func WithExtractor 

func WithExtractor(extractor SessionExtractor) Option

WithExtractor injects a session extractor.

func WithPlanner 

func WithPlanner(planner QueryPlanner) Option

WithPlanner injects a query planner.

func WithProjectConfig 

func WithProjectConfig(cfg ProjectConfig) Option

WithProjectConfig applies a project config to the service.

func WithPromotionPolicy 

func WithPromotionPolicy(policy PromotionPolicy) Option

WithPromotionPolicy injects a promotion policy.

type ProjectConfig 

type ProjectConfig struct {
	Version     int           `json:"version"`
	Project     string        `json:"project,omitempty"`
	Conventions ConventionSet `json:"conventions"`
}

ProjectConfig stores project-local workflow defaults.

func DefaultProjectConfig 

func DefaultProjectConfig(project string) ProjectConfig

DefaultProjectConfig returns a ready-to-save config for a project.

func LoadConfig 

func LoadConfig(path string) (*ProjectConfig, error)

LoadConfig loads a project config from disk.

type PromotionCandidate 

type PromotionCandidate struct {
	KnowledgeID string                       `json:"knowledge_id,omitempty"`
	Kind        PromotionKind                `json:"kind,omitempty"`
	Title       string                       `json:"title,omitempty"`
	Content     string                       `json:"content"`
	SourceURL   string                       `json:"source_url,omitempty"`
	Author      string                       `json:"author,omitempty"`
	Collection  string                       `json:"collection,omitempty"`
	Metadata    map[string]string            `json:"metadata,omitempty"`
	Entities    []cortexdb.ToolEntityInput   `json:"entities,omitempty"`
	Relations   []cortexdb.ToolRelationInput `json:"relations,omitempty"`
}

PromotionCandidate is one knowledge item proposed by the workflow extractor.

type PromotionKind 

type PromotionKind string

PromotionKind classifies durable knowledge candidates. 

const (
	PromotionKindDecision   PromotionKind = "decision"
	PromotionKindPreference PromotionKind = "preference"
	PromotionKindMilestone  PromotionKind = "milestone"
	PromotionKindProblem    PromotionKind = "problem"
	PromotionKindNote       PromotionKind = "note"
)

type PromotionPolicy 

type PromotionPolicy interface {
	Select(ctx context.Context, transcript Transcript, state SessionState, candidates []PromotionCandidate) ([]PromotionCandidate, error)
}

PromotionPolicy filters or reorders extracted promotion candidates.

type ProtocolStep 

type ProtocolStep struct {
	Name      string `json:"name"`
	Action    string `json:"action"`
	Required  bool   `json:"required"`
	Completed bool   `json:"completed"`
	Note      string `json:"note,omitempty"`
}

ProtocolStep is one deterministic step in the reply workflow.

type QueryPlanner 

type QueryPlanner interface {
	Plan(ctx context.Context, query string, state SessionState) (*cortexdb.RetrievalPlan, error)
}

QueryPlanner produces retrieval plans for lexical or hybrid recall.

type RecallRequest 

type RecallRequest struct {
	Query            string                  `json:"query"`
	UserID           string                  `json:"user_id,omitempty"`
	SessionID        string                  `json:"session_id,omitempty"`
	Scope            string                  `json:"scope,omitempty"`
	Namespace        string                  `json:"namespace,omitempty"`
	Collection       string                  `json:"collection,omitempty"`
	TopKMemories     int                     `json:"top_k_memories,omitempty"`
	TopKKnowledge    int                     `json:"top_k_knowledge,omitempty"`
	RetrievalMode    string                  `json:"retrieval_mode,omitempty"`
	DisableMemory    bool                    `json:"disable_memory,omitempty"`
	DisableKnowledge bool                    `json:"disable_knowledge,omitempty"`
	DisableGraph     bool                    `json:"disable_graph,omitempty"`
	GraphLight       bool                    `json:"graph_light,omitempty"`
	MaxContextChars  int                     `json:"max_context_chars,omitempty"`
	MaxContextChunks int                     `json:"max_context_chunks,omitempty"`
	Plan             *cortexdb.RetrievalPlan `json:"plan,omitempty"`
	State            SessionState            `json:"state,omitempty"`
}

RecallRequest resolves a plan and returns a fused memory/knowledge pack.

type RecallResponse 

type RecallResponse struct {
	Plan     cortexdb.RetrievalPlan       `json:"plan"`
	Decision cortexdb.RetrievalDecision   `json:"decision"`
	Response cortexdb.BrainRecallResponse `json:"response"`
}

RecallResponse contains the fused recall pack plus the resolved plan.

type ReplyProtocolRequest 

type ReplyProtocolRequest struct {
	Identity string        `json:"identity,omitempty"`
	Recall   RecallRequest `json:"recall"`
}

ReplyProtocolRequest prepares a grounded reply workflow.

type ReplyProtocolResponse 

type ReplyProtocolResponse struct {
	WakeUp          WakeUpLayersResponse `json:"wake_up"`
	ShouldGround    bool                 `json:"should_ground"`
	RecommendedMode string               `json:"recommended_mode"`
	Steps           []ProtocolStep       `json:"steps,omitempty"`
	Notes           []string             `json:"notes,omitempty"`
}

ReplyProtocolResponse returns wake-up layers plus a deterministic grounding recommendation.

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service is the opinionated workflow layer on top of CortexDB memory and knowledge primitives.

func New 

func New(db *cortexdb.DB, planner QueryPlanner, extractor SessionExtractor, opts ...Option) (*Service, error)

New constructs a memory workflow facade.

func (*Service) AppendDiaryEntry 

func (s *Service) AppendDiaryEntry(ctx context.Context, req DiaryEntryRequest) (*DiaryEntryResponse, error)

AppendDiaryEntry stores one diary entry in a dedicated diary namespace.

func (*Service) CloseSession 

func (s *Service) CloseSession(ctx context.Context, req CloseSessionRequest) (*CloseSessionResponse, error)

CloseSession optionally promotes extracted durable knowledge at session end.

func (*Service) GetTranscript 

func (s *Service) GetTranscript(ctx context.Context, req GetTranscriptRequest) (*GetTranscriptResponse, error)

GetTranscript reconstructs the original transcript order from stored episodes.

func (*Service) IngestTranscript 

func (s *Service) IngestTranscript(ctx context.Context, req IngestTranscriptRequest) (*IngestTranscriptResponse, error)

IngestTranscript stores a transcript as exchange-shaped episodic memory chunks.

func (*Service) ListDiaryEntries 

func (s *Service) ListDiaryEntries(ctx context.Context, req DiaryListRequest) (*DiaryListResponse, error)

ListDiaryEntries returns chronological diary entries for a resolved bucket.

func (*Service) ListEpisodes 

func (s *Service) ListEpisodes(ctx context.Context, req ListEpisodesRequest) (*ListEpisodesResponse, error)

ListEpisodes lists stored exchange-shaped episodic memories for a resolved bucket.

func (*Service) NewMCPServer 

func (s *Service) NewMCPServer(opts MCPServerOptions) (*mcp.Server, error)

NewMCPServer returns an MCP server that exposes the memoryflow tool surface.

func (*Service) PrepareReply 

func (s *Service) PrepareReply(ctx context.Context, req ReplyProtocolRequest) (*ReplyProtocolResponse, error)

PrepareReply returns deterministic protocol guidance plus wake-up layers.

func (*Service) Recall 

func (s *Service) Recall(ctx context.Context, req RecallRequest) (*RecallResponse, error)

Recall resolves a retrieval plan and delegates to the CortexDB brain facade.

func (*Service) ResolveTaxonomy 

func (s *Service) ResolveTaxonomy(base Taxonomy, hint SourceHint) Taxonomy

ResolveTaxonomy resolves workflow taxonomy for external callers using the service conventions.

func (*Service) WakeUp 

func (s *Service) WakeUp(ctx context.Context, req WakeUpRequest) (*WakeUpResponse, error)

WakeUp assembles a compact startup context by prepending identity to a recall pack.

func (*Service) WakeUpLayers 

func (s *Service) WakeUpLayers(ctx context.Context, req WakeUpLayersRequest) (*WakeUpLayersResponse, error)

WakeUpLayers returns explicit L0-L3 wake-up tiers.

type SessionExtractor 

type SessionExtractor interface {
	Extract(ctx context.Context, transcript Transcript, state SessionState) ([]PromotionCandidate, error)
}

SessionExtractor proposes durable knowledge promotions from a transcript.

type SessionState 

type SessionState struct {
	UserID     string         `json:"user_id,omitempty"`
	SessionID  string         `json:"session_id,omitempty"`
	Namespace  string         `json:"namespace,omitempty"`
	Wing       string         `json:"wing,omitempty"`
	Room       string         `json:"room,omitempty"`
	Tags       []string       `json:"tags,omitempty"`
	Taxonomy   Taxonomy       `json:"taxonomy,omitempty"`
	Transcript *Transcript    `json:"transcript,omitempty"`
	Metadata   map[string]any `json:"metadata,omitempty"`
}

SessionState provides planner context for recall and wake-up flows.

type SourceHint 

type SourceHint struct {
	Project string   `json:"project,omitempty"`
	Path    string   `json:"path,omitempty"`
	Source  string   `json:"source,omitempty"`
	Title   string   `json:"title,omitempty"`
	Tags    []string `json:"tags,omitempty"`
}

SourceHint is the non-LLM input used to resolve a taxonomy from deterministic conventions.

type Taxonomy 

type Taxonomy struct {
	Kind     string            `json:"kind,omitempty"`
	Wing     string            `json:"wing,omitempty"`
	Room     string            `json:"room,omitempty"`
	Source   string            `json:"source,omitempty"`
	Tags     []string          `json:"tags,omitempty"`
	Entities []string          `json:"entities,omitempty"`
	Labels   map[string]string `json:"labels,omitempty"`
}

Taxonomy describes the workflow-level memory placement and labeling metadata.

func ResolveTaxonomy 

func ResolveTaxonomy(base Taxonomy, hint SourceHint, conventions ConventionSet) Taxonomy

ResolveTaxonomy applies deterministic project conventions to a base taxonomy.

type Toolbox 

type Toolbox struct {
	// contains filtered or unexported fields
}

Toolbox exposes memoryflow as a tool-call surface.

func NewToolbox 

func NewToolbox(service *Service) (*Toolbox, error)

NewToolbox constructs a tool facade for a workflow service.

func (*Toolbox) Call 

func (t *Toolbox) Call(ctx context.Context, name string, input json.RawMessage) (any, error)

Call dispatches a tool call into the workflow service.

func (*Toolbox) Definitions 

func (t *Toolbox) Definitions() []cortexdb.ToolDefinition

Definitions returns JSON-schema-like tool definitions.

type Transcript 

type Transcript struct {
	SessionID string           `json:"session_id,omitempty"`
	UserID    string           `json:"user_id,omitempty"`
	Source    string           `json:"source,omitempty"`
	Title     string           `json:"title,omitempty"`
	Turns     []TranscriptTurn `json:"turns"`
}

Transcript is the normalized input to the memory workflow ingest path.

type TranscriptTurn 

type TranscriptTurn struct {
	Role      string    `json:"role"`
	Content   string    `json:"content"`
	Timestamp time.Time `json:"timestamp,omitempty"`
	SourceID  string    `json:"source_id,omitempty"`
}

TranscriptTurn is one normalized turn from a conversation transcript.

type WakeUpLayer 

type WakeUpLayer struct {
	Level WakeUpLevel `json:"level"`
	Title string      `json:"title,omitempty"`
	Text  string      `json:"text"`
}

WakeUpLayer is one wake-up context tier.

type WakeUpLayersRequest 

type WakeUpLayersRequest struct {
	Identity string        `json:"identity,omitempty"`
	Recall   RecallRequest `json:"recall"`
}

WakeUpLayersRequest requests all wake-up context tiers.

type WakeUpLayersResponse 

type WakeUpLayersResponse struct {
	Layers []WakeUpLayer  `json:"layers"`
	Recall RecallResponse `json:"recall"`
}

WakeUpLayersResponse returns all wake-up context tiers plus the recall payload.

type WakeUpLevel 

type WakeUpLevel string

WakeUpLevel identifies one context density tier. 

const (
	WakeUpLevelL0 WakeUpLevel = "L0"
	WakeUpLevelL1 WakeUpLevel = "L1"
	WakeUpLevelL2 WakeUpLevel = "L2"
	WakeUpLevelL3 WakeUpLevel = "L3"
)

type WakeUpRequest 

type WakeUpRequest struct {
	Identity string        `json:"identity,omitempty"`
	Recall   RecallRequest `json:"recall"`
}

WakeUpRequest assembles a compact startup context for an agent.

type WakeUpResponse 

type WakeUpResponse struct {
	Text   string         `json:"text"`
	Recall RecallResponse `json:"recall"`
}

WakeUpResponse contains the final startup text and the underlying recall response.

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.