memory

type AIMemorySelector ¶

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

AIMemorySelector 是基于模型调用的记忆选择器.

func NewAIMemorySelector(fn ModelQueryFunc) *AIMemorySelector

func (s *AIMemorySelector) Select(ctx context.Context, query string, headers []MemoryHeader, opts SelectOpts) ([]MemoryHeader, error)

type Backupper ¶

type Backupper interface {
	// Backup 在写入前备份指定路径的文件.
	// 如果文件不存在,实现应静默跳过(新建文件无需备份).
	// path 是绝对路径;ctx 用于超时/取消控制.
	Backup(ctx context.Context, path string) error
}

Backupper is the pre-write backup interface.

Shape: synchronous callback. Store calls Snapshot synchronously before mutating on-disk memory files, letting the consumer implementation capture a version or rollback point.

形态: 同步回调. Store 在改动磁盘记忆文件前同步调 Snapshot, 让消费者 实现捕获版本或回滚点.

Backupper 是写入前备份接口.

升华改进(ELEVATED): 用接口而非具体类型(*engine.FileHistory)打破循环依赖-- memory 包不能 import engine 包(engine 已经 import memory). engine.FileHistory 实现此接口,memory.fileStore 通过 WithFileHistory 注入. 这和 observer 的消费思路一致:通过接口解耦,让 engine 注入具体实现.

精妙之处(CLEVER): 只暴露一个方法--Backup(ctx, path) error. fileStore 不关心备份的内部实现(内容寻址,SHA256,最大快照数), 只关心"在写入 path 前,帮我备份一下". 替代方案:传入 *engine.FileHistory(循环依赖,直接否决). 替代方案:传入 func(ctx, path) error(函数类型,但接口更可组合,可 mock).

type CompositeScorer ¶

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

CompositeScorer 将多个评分器加权组合.

升华改进(ELEVATED): 支持叠加而非替换(宪法第 8 条). 编程评分器 + 仓储评分器可以共存,加权融合. 替代方案:单评分器(锁定单场景).

使用示例:

composite := NewCompositeScorer(
    WeightedScorer{Scorer: &TextScorer{}, Weight: 0.7},
    WeightedScorer{Scorer: &WarehouseScorer{}, Weight: 0.3},
)

func NewCompositeScorer(scorers ...WeightedScorer) *CompositeScorer

func (cs *CompositeScorer) Add(ws WeightedScorer)

func (cs *CompositeScorer) Name() string

func (cs *CompositeScorer) Remove(name string) bool

func (cs *CompositeScorer) Score(query string, header *MemoryHeader) float64

type ConflictPolicy ¶

type ConflictPolicy int

ConflictPolicy 定义 Push 时遇到写冲突的处理策略.

冲突场景:两个 session 同时修改了同一记忆文件, 后 Push 的一方发现服务器版本已被修改(HTTP 412 / git diverge).

const (
	// ConflictLocalWins 本地版本覆盖服务器版本.
	//
	// 适用:CLI 单用户,用户正在活跃编辑,不希望 teammate 的远端更新覆盖自己的工作.
	// 早期实现 的行为:412 时刷新 serverChecksums 再 push,等价于本地覆盖.
	// 注意:另一方的修改会丢失(静默),不适用于高并发写场景.
	ConflictLocalWins ConflictPolicy = iota

	// ConflictServerWins 服务器版本覆盖本地版本.
	//
	// 适用:HTTP API 无状态模式--"本地"是临时容器,一旦冲突说明本地已过时,
	// 应丢弃本地,以远端为准.
	// 语义:Pull 成功后 Push,若 Pull 前有未提交的本地更改则丢弃.
	ConflictServerWins

	// ConflictMerge 三路合并,冲突时产生冲突标记(<<<< HEAD).
	//
	// 适用:Git 后端,多人协作,需要完整历史记录.
	// Git 的 rebase/merge 处理大多数非交叉修改,只有真正冲突才产生标记.
	// AI 可以读取并解决冲突标记,不需要人工介入.
	ConflictMerge

	// ConflictFail 发生冲突时返回错误,由调用方决定如何处理.
	//
	// 适用:需要强一致性的场景(金融,医疗),任何冲突都需要显式确认.
	// 调用方可以提示用户,重试,或放弃本次写入.
	ConflictFail
)

func (p ConflictPolicy) String() string

type DefaultCodeExtractor ¶

type DefaultCodeExtractor struct{}

DefaultCodeExtractor 编程场景的默认记忆提取器.

提取策略:

• 每 5 轮对话检查一次(避免频繁提取浪费 API 调用)
• 关注:项目结构,代码规范,技术决策,用户偏好
• 输出格式:YAML frontmatter + markdown 正文
• 最多 5 轮(提取任务通常 1-2 轮就够了)

func (e *DefaultCodeExtractor) AllowedTools() []string

func (e *DefaultCodeExtractor) BuildPrompt(existingMemories []*Entry, newMessageCount int) string

func (e *DefaultCodeExtractor) MaxTurns() int

func (e *DefaultCodeExtractor) Name() string

func (e *DefaultCodeExtractor) ShouldExtract(turnCount, lastExtractTurn int) bool

type Entry ¶

type Entry struct {
	Name        string    `json:"name"`
	Description string    `json:"description"`
	Type        Type      `json:"type"`
	Content     string    `json:"content"`
	Path        string    `json:"path,omitempty"` // 文件路径(文件存储)
	ModTime     time.Time `json:"mod_time,omitempty"`
}

Entry 是一条记忆记录.

type ExternalScorer ¶

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

ExternalScorer 桥接外部进程实现的评分器(跨语言支持).

升华改进(ELEVATED): 仓储团队可以用 Python 写评分器, 通过 stdin/stdout JSON 通信.引擎内部看到的仍然是 Go 接口. 替代方案:要求所有评分器用 Go 实现(锁定语言生态).

使用示例(Python 端):

# warehouse_scorer.py
import json, sys
for line in sys.stdin:
    req = json.loads(line)
    score = my_scoring_logic(req["query"], req["name"], req["type"])
    print(json.dumps({"score": score}))

使用示例(Go 端):

scorer, _ := NewExternalScorer(ctx, ExternalScorerOptions{
    Name:     "warehouse",
    Command:  "python3",
    Args:     []string{"warehouse_scorer.py"},
    Executor: execenv.DefaultExecutor{},
})
composite.Add(WeightedScorer{Scorer: scorer, Weight: 0.3})

通信协议(JSON Lines):

请求:{"query": "数据库配置", "name": "db_config", "description": "...", "type": "project"}
响应:{"score": 0.85}

Score 失败时返回 0.0(不阻断主流程).

func NewExternalScorer(ctx context.Context, opts ExternalScorerOptions) (*ExternalScorer, error)

func (s *ExternalScorer) Close() error

func (s *ExternalScorer) Name() string

func (s *ExternalScorer) Score(query string, header *MemoryHeader) float64

type ExternalScorerOptions ¶

type ExternalScorerOptions struct {
	// Name 是评分器名称, 用于日志和 CompositeScorer.Remove.
	Name string

	// Command 是外部进程的可执行路径 (python3 / node / 自定义 binary).
	Command string

	// Args 是传给 Command 的参数列表, 不含 Command 本身.
	Args []string

	// Executor 是子进程启动抽象 (M1 方案 β 严格 DI). 必填, nil 即 panic.
	// 本地 CLI 传 execenv.DefaultExecutor{}, 云端 SaaS 由 platform 层传
	// sandbox.Backend. ClassPluginTool 告诉 backend "这是第三方 plugin 代码,
	// 零信任隔离" — 和 plugin shell tool 同策略.
	Executor execenv.Executor
}

ExternalScorerOptions 是 NewExternalScorer 的构造参数.

对齐 GitSyncOptions 风格 (opts struct DI), 便于未来扩容 (如 WorkDir, 自定义 Env) 不破 API.

type FileStoreOption ¶

type FileStoreOption func(*fileStore)

FileStoreOption 是 NewFileStoreWithOptions 的配置选项.

func WithFileHistory(bk Backupper) FileStoreOption

memory.WithFileHistory(e.fileHistory)

func WithFreshness(cfg FreshnessConfig) FileStoreOption

func WithMemorySelector(sel MemorySelector) FileStoreOption

func WithObserver(obs flyto.EventObserver) FileStoreOption

func WithScorer(scorer RelevanceScorer) FileStoreOption

func WithSecretGuard(g security.SecretGuard) FileStoreOption

func WithStrictSymlink() FileStoreOption

func WithSyncAdapter(adapter SyncAdapter, cfg SyncConfig) FileStoreOption

func WithTypeRegistry(reg *MemoryTypeRegistry) FileStoreOption

type FreshnessConfig ¶

type FreshnessConfig struct {
	// GlobalThreshold 全局新鲜度阈值.
	// 记忆年龄超过此值时触发警告.
	// 0 = 总是触发警告(任何年龄的记忆都提示可能过时).
	// 典型值:24 * time.Hour(默认),2 * time.Hour(仓储),0(医疗强制)
	GlobalThreshold time.Duration

	// TypeOverrides 按记忆类型覆盖阈值.
	// key 是 Type 字符串("user"/"feedback"/"project"/"reference").
	// 未出现在此 map 中的类型使用 GlobalThreshold.
	//
	// 示例:
	//   TypeOverrides: map[string]time.Duration{
	//     "project": 12 * time.Hour,  // 项目上下文半天就可能过时
	//     "user":    7 * 24 * time.Hour, // 用户偏好一周才变
	//   }
	TypeOverrides map[string]time.Duration
}

FreshnessConfig 配置记忆新鲜度检测策略.

精妙之处(CLEVER): 用"零值禁用"约定统一 nil 和 zero-value 的语义-- GlobalThreshold == 0 表示"总是警告"(不是"从不警告"), 这对医疗/金融场景(任何过时记忆都需警告)自然成立. 调用方传 nil 时,引擎不初始化 FreshnessConfig,不产生任何警告-- nil 与 GlobalThreshold==0 是两种不同语义,需通过指针区分. 在 engine.Config 中用 *FreshnessConfig,nil = 不启用新鲜度功能.

func DefaultFreshnessConfig() FreshnessConfig

func (c FreshnessConfig) ThresholdFor(t Type) time.Duration

type Frontmatter ¶

type Frontmatter struct {
	Name        string // 记忆名称(唯一标识)
	Description string // 一行描述,用于相关性检索
	Type        Type   // 记忆类型:user/feedback/project/reference
	// Version 是 frontmatter 格式 schema 版本(从 1 开始).
	// 0 = 未设置(旧文件),调用方应规范化为 1.
	Version int
}

Frontmatter 是记忆文件的元数据头部. 对应原项目中每个 .md 文件的 YAML frontmatter 部分.

版本兼容(INF-6):

Version 字段记录 frontmatter 格式版本.
旧文件(无 version 行)解析后 Version == 0,ScanMemoryDir/ParseFrontmatter
调用方将其规范化为 1(对应 frontmatterCurrentVersion).

func ParseFrontmatter(content string) (fm Frontmatter, body string, ok bool)

type FrontmatterMigrateFunc ¶

type FrontmatterMigrateFunc func(*Frontmatter) error

FrontmatterMigrateFunc 是一个 frontmatter 迁移函数的类型. 输入是版本 N 的 Frontmatter,函数就地修改为版本 N+1 的格式.

约定:

• 幂等:重复调用不产生副作用
• 无损:不丢失原有字段的语义信息
• 不修改 Version 字段:migrateFrontmatter 统一递增

type GitMode ¶

type GitMode int

GitMode 定义 GitSyncAdapter 的工作模式.

const (
	// GitModeStandalone 独立仓库模式:localDir 本身是一个 git repo.
	// Pull = git pull --rebase --autostash
	// Push = git add -A && git commit && git push
	GitModeStandalone GitMode = iota

	// GitModeEmbedded 嵌入模式:localDir 在项目 git repo 内,使用专属分支.
	// Pull = git fetch origin && git checkout flyto/memory && git rebase origin/flyto/memory
	// Push = git add <localDir> && git commit && git push origin flyto/memory
	GitModeEmbedded
)

type GitSyncAdapter ¶

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

GitSyncAdapter 是基于 git 命令的 SyncAdapter 实现.

零值不可用,必须通过 NewGitSyncAdapter 构造.

func NewGitSyncAdapter(opts GitSyncOptions) *GitSyncAdapter

func (g *GitSyncAdapter) InitRepo(ctx context.Context, localDir string, remoteURL string) error

func (g *GitSyncAdapter) IsAvailable() bool

func (g *GitSyncAdapter) Pull(ctx context.Context, localDir string) (int, error)

func (g *GitSyncAdapter) Push(ctx context.Context, localDir string, policy ConflictPolicy) (int, error)

type GitSyncOptions ¶

type GitSyncOptions struct {
	// Mode 工作模式,默认 GitModeStandalone.
	Mode GitMode

	// Remote git remote 名称,默认 "origin".
	Remote string

	// Branch 分支名,默认:
	//   - Standalone: "main"
	//   - Embedded: "flyto/memory"
	Branch string

	// CommitAuthorName git commit 的作者名,默认 "Flyto Agent".
	CommitAuthorName string

	// CommitAuthorEmail git commit 的作者邮箱,默认 "agent@flyto.local".
	CommitAuthorEmail string

	// GitBin git 二进制路径,默认在 PATH 中查找 "git".
	// 用于测试时注入 mock git 路径.
	GitBin string

	// Executor 是子进程启动抽象 (M1 方案 β 严格 DI). 必填, 零值会在
	// NewGitSyncAdapter 里 panic. 本地 CLI 传 execenv.DefaultExecutor{},
	// 云端 SaaS 由 platform 层传 sandbox.Backend (ClassMemoryGit 映射到
	// system pod 或 tenant VM 路由决策发生在 backend 内).
	Executor execenv.Executor
}

GitSyncOptions 是 GitSyncAdapter 的构造选项.

type MemoryExtractor ¶

type MemoryExtractor interface {
	// Name 返回提取器的名称标识.
	Name() string

	// ShouldExtract 判断是否应触发提取.
	// turnCount: 当前对话已完成的轮数
	// lastExtractTurn: 上次提取时的轮数(0 = 从未提取)
	ShouldExtract(turnCount int, lastExtractTurn int) bool

	// BuildPrompt 构建提取提示词.
	// existingMemories: 当前已有的记忆条目(避免重复提取)
	// newMessageCount: 自上次提取以来的新消息数(SubAgent 凭此精准定位分析范围)
	// 返回发送给提取子 agent 的完整 prompt.
	//
	// 升华改进(ELEVATED): 相比早期方案 Go 签名 BuildPrompt(existingMemories []*Entry),
	// 加入 newMessageCount--早期实现 buildExtractAutoOnlyPrompt(newMessageCount, existingMemories)
	// 会在 prompt 中注入 "Analyze the most recent ~N messages",让 SubAgent 只看最近的
	// 消息而非全部历史,避免重复提取旧内容.我们把这个参数提升到接口层,
	// 所有场景(编程/仓储/金融)都能利用精准定位.
	// 替代方案:由 Engine 在调用后包装一句话(职责扩散,场景 prompt 无法定制定位粒度).
	BuildPrompt(existingMemories []*Entry, newMessageCount int) string

	// AllowedTools 返回提取代理允许使用的工具名列表.
	// 提取子 agent 只能使用这些工具,防止越权操作.
	AllowedTools() []string

	// MaxTurns 返回提取代理的最大轮数.
	MaxTurns() int
}

MemoryExtractor 从对话中提取值得记住的信息.

升华改进(ELEVATED): 接口只定义策略,执行由 Engine 的 SubAgent fork 模式负责. 这样 Extractor 完全不知道 API,模型,token 这些执行细节, 只专注于"提取什么"和"什么时候提取". 替代方案:Extractor 自己持有 API client 直接调用模型(职责越界,变成小 Engine).

Shape: synchronous callback. Engine calls ShouldExtract / Extract at turn boundaries; the extractor decides if extraction is warranted and produces candidate memories.

形态: 同步回调. 引擎在 turn 边界同步调 ShouldExtract / Extract; extractor 判断是否该抽取并产出候选记忆.

type MemoryHeader ¶

type MemoryHeader struct {
	Frontmatter Frontmatter // 解析出的 frontmatter 元数据
	Path        string      // 文件绝对路径
	ModTime     time.Time   // 文件最后修改时间
}

MemoryHeader 是记忆文件的头部信息(轻量级,不含正文). 用于列表展示和相关性评估,避免加载完整内容.

func ScanMemoryDir(dir string) ([]MemoryHeader, error)

func SelectRelevant(query string, headers []MemoryHeader, limit int, scorer ...RelevanceScorer) []MemoryHeader

type MemorySelector ¶

type MemorySelector interface {
	Select(ctx context.Context, query string, headers []MemoryHeader, opts SelectOpts) ([]MemoryHeader, error)
}

MemorySelector 是批量记忆选择器接口.

升华改进(ELEVATED): 与 RelevanceScorer 的区别--

• RelevanceScorer: 单条打分(0.0~1.0),适合排序 MemorySelector: 批量选择,一次 AI 调用完成,支持额外过滤参数

替代方案:<复用 RelevanceScorer 逐条打分再排序> - 否决: AI 打分成本高,逐条打分 token 消耗是批量选择的数倍.

错误契约 (2026-04-14 反转):

• ctx 取消: 返回 (nil, nil), 正常中止不算错误.
• 其他错误 (模型请求失败 / JSON 解析失败 / ...): 返回 (nil, err), 由调用方 (Store) 决定 fallback 策略.

不在 selector 内部 fallback 的原因: selector 无 back-reference 到 调用方 Store 的配置 (scorer / typeRegistry / ...), 内部 fallback 只能用 nil 参数, 会静默忽略用户的 WithScorer 等配置. fallback 必须由持有配置 的层 (Store.FindRelevant) 做, 才能把 s.scorer 正确传给 SelectRelevant.

Shape: synchronous callback. Store.FindRelevant calls Select synchronously during prompt assembly; the selector implementation (AI or heuristic) ranks MemoryHeader candidates for the query.

形态: 同步回调. Store.FindRelevant 在拼 prompt 时同步调 Select; selector 实现 (AI 或启发式) 对 MemoryHeader 候选按 query 排序.

type MemoryTypeInfo ¶

type MemoryTypeInfo struct {
	Name          string   // 类型名称:"user" / "inventory_rule" / ...
	Scope         string   // 作用域:"private" / "team" / "org" / "local"
	Description   string   // 给模型看的描述(会注入到系统提示词)
	WhenToSave    string   // 什么时候应该保存这种记忆
	HowToUse      string   // 怎么使用这种记忆
	BodyStructure string   // 记忆体的推荐格式(如 "规则 → Why → How to apply")
	Examples      []string // 示例
	SortOrder     int      // 在索引中的排列顺序
}

MemoryTypeInfo 描述一种记忆类型的完整元信息. 这些信息会注入到系统提示词中,指导模型何时保存,如何使用该类型的记忆.

type MemoryTypeRegistry ¶

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

MemoryTypeRegistry 是分层的记忆类型注册表.

精妙之处(CLEVER): parent 指针实现只读继承链. 查询时 local 优先(近端覆盖远端),沿 parent 链向上冒泡. 注册只写入本级 local map,不会污染上级.

var DefaultTypeRegistry *MemoryTypeRegistry

func NewTypeRegistry(opts ...RegistryOption) *MemoryTypeRegistry

func (r *MemoryTypeRegistry) All() []*MemoryTypeInfo

func (r *MemoryTypeRegistry) FormatForPrompt(format PromptFormat) string

func (r *MemoryTypeRegistry) Get(name string) *MemoryTypeInfo

func (r *MemoryTypeRegistry) IsRegistered(name string) bool

func (r *MemoryTypeRegistry) ParseType(raw string) (string, bool)

func (r *MemoryTypeRegistry) Register(info *MemoryTypeInfo)

type ModelQueryFunc ¶

type ModelQueryFunc func(ctx context.Context, systemPrompt, userPrompt string) (string, error)

ModelQueryFunc 是模型查询函数类型.

打破 memory→engine 的循环依赖:memory 包只依赖此函数签名, engine 层传入闭包实现,不需要 memory import flyto 包.

systemPrompt: 系统提示词 userPrompt: 用户消息 返回: 模型的纯文本回复,error

type NoopSyncAdapter ¶

type NoopSyncAdapter struct{}

NoopSyncAdapter 是不执行任何同步的空实现.

所有现有 NewFileStore* 调用默认使用此实现(即不同步), 向后兼容--现有代码无需任何修改即可升级到支持同步的版本.

精妙之处(CLEVER): IsAvailable() 始终返回 false, fileStore 的 shouldPull/shouldPush 在 IsAvailable=false 时立即跳过, 不会有任何锁竞争或时间戳检查开销. 如果用"空方法直接返回"代替,shouldPull 逻辑里仍然需要 nil 检查,代码更复杂.

func (n *NoopSyncAdapter) IsAvailable() bool

func (n *NoopSyncAdapter) Pull(_ context.Context, _ string) (int, error)

func (n *NoopSyncAdapter) Push(_ context.Context, _ string, _ ConflictPolicy) (int, error)

type PromptFormat ¶

type PromptFormat string

PromptFormat 提示词输出格式.

const (
	FormatXML      PromptFormat = "xml"
	FormatMarkdown PromptFormat = "markdown"
	FormatJSON     PromptFormat = "json"
)

func AutoPromptFormat(modelID string) PromptFormat

type PullPolicy ¶

type PullPolicy int

PullPolicy 定义何时自动触发 Pull 操作.

Pull 的代价因后端不同而差异巨大:

• Git 本地 fetch:毫秒级
• HTTP API(304 Not Modified):网络 RTT,通常 50-200ms
• HTTP API(需要传输内容):RTT + 传输时间,可达数秒

精妙之处(CLEVER): PullPolicy 是 Pull 时机的纯策略描述,不含时间戳状态-- 状态(lastPullTime,pulled 标志)保存在 fileStore 中. 这样同一个 PullPolicy 值可以安全地在多个 store 实例间共享(无数据竞争).

const (
	// PullOnSessionStart 每个 store 实例生命周期内只 Pull 一次.
	//
	// 适用:CLI 模式,session 生命周期与 store 生命周期一致.
	// "首次读操作"触发 Pull,之后不再 Pull,保持 session 内的一致性.
	PullOnSessionStart PullPolicy = iota

	// PullWithTTL 距上次 Pull 超过 SyncConfig.PullTTL 才重新 Pull.
	//
	// 适用:SDK 嵌入,长生命周期服务,请求频繁但不希望每次都 Pull.
	// TTL 是新鲜度与性能的平衡点--TTL 越短一致性越强,TTL 越长 I/O 越少.
	PullWithTTL

	// PullAlways 每次读操作(List/FindRelevant)前都 Pull.
	//
	// 适用:强一致性要求,允许每次读都承受 Pull 开销(如审计日志场景).
	// 警告:高频读场景下会显著增加延迟,谨慎使用.
	PullAlways

	// PullNever 不自动 Pull.
	//
	// 适用:离线场景,纯写场景,调用方手动控制同步时机.
	// 也是 NoopSyncAdapter 的隐含策略(IsAvailable=false 时自动不 Pull).
	PullNever
)

type RegistryOption ¶

type RegistryOption func(*MemoryTypeRegistry)

RegistryOption 是 NewTypeRegistry 的配置选项.

func WithParent(parent *MemoryTypeRegistry) RegistryOption

type RelevanceScorer ¶

type RelevanceScorer interface {
	Name() string
	Score(query string, header *MemoryHeader) float64
}

RelevanceScorer 记忆相关性评分器接口.

升华改进(ELEVATED): 从包级函数提升为接口,支持场景可插拔. 编程场景用文本相似度,仓储场景可能按 SKU/订单号匹配, 法律场景可能按法条编号匹配.不同场景注册不同评分器. 替代方案:硬编码文本相似度函数(原始设计,锁死评分算法).

参数传 *MemoryHeader 而非 name+description: 宽接口缩窄容易,窄接口拓宽要改所有实现. 评分器可以利用 Type,ModTime 等额外信息做更精准的评分.

Shape: synchronous callback. Store calls Score synchronously during FindRelevant to rank memory candidates for the current prompt; consumer can plug keyword-based / embedding / LLM scorers.

形态: 同步回调. Store 在 FindRelevant 期间同步调 Score, 对当前 prompt 排序记忆候选; 消费者可插入关键词 / embedding / LLM 等 scorer.

type SelectOpts ¶

type SelectOpts struct {
	Limit           int             // 最多返回几条,<=0 则用 defaultRelevanceLimit(5)
	RecentTools     []string        // 最近用到的工具名(避免重推这些工具的 ref docs)
	AlreadySurfaced map[string]bool // 本 session 已展示过的文件路径(去重)
}

SelectOpts 是记忆选择器的选项.

type Store ¶

type Store interface {
	// Save 保存一条记忆.
	Save(ctx context.Context, entry *Entry) error

	// List 列出所有记忆(按修改时间倒序).
	List(ctx context.Context) ([]*Entry, error)

	// FindRelevant 查找与查询相关的记忆.
	FindRelevant(ctx context.Context, query string, limit int) ([]*Entry, error)

	// Delete 删除一条记忆.
	Delete(ctx context.Context, name string) error

	// UpdateIndex 更新 MEMORY.md 索引文件.
	UpdateIndex(ctx context.Context) error

	// Dir 返回记忆文件的存储目录(绝对路径).
	// 记忆提取子 agent 用此路径限制 Edit/Write 只能写入记忆目录,
	// hasMemoryWritesSince 用此路径判断主 agent 是否已写过记忆.
	Dir() string
}

Store 是记忆存储接口.

Shape: synchronous callback for writes, pull for reads. Engine calls Save / Delete synchronously after extraction; Get / List / FindRelevant serve as pull API for UIs and the prompt assembly step.

形态: 写是同步回调, 读是 pull. 引擎在抽取后同步调 Save / Delete; Get / List / FindRelevant 作为 pull API 供 UI 和 prompt 拼装使用.

func NewFileStore(cwd string) Store

func NewFileStoreWithBaseDir(baseDir string) Store

func NewFileStoreWithOptions(cwd string, opts ...FileStoreOption) Store

type SyncAdapter ¶

type SyncAdapter interface {
	// Pull 从远端拉取最新状态到本地目录.
	//
	// 实现约定:
	//   - 必须是幂等的:多次 Pull 结果相同
	//   - 不应删除本地存在但远端不存在的文件(防止意外丢失)
	//     除非 ConflictServerWins 语义要求(由实现者决定)
	//   - context 取消时应尽快返回
	//
	// 返回值:pulled 是实际更新(新增或覆盖)的文件数,0 表示无变化.
	Pull(ctx context.Context, localDir string) (pulled int, err error)

	// Push 将本地目录的变化上传到远端.
	//
	// policy 控制写冲突时的行为:
	//   - ConflictLocalWins:本地覆盖远端
	//   - ConflictServerWins:检测到冲突时先 Pull 再 Push(服务器版本保留)
	//   - ConflictMerge:三路合并(Git 后端支持,HTTP 后端可能不支持)
	//   - ConflictFail:冲突时直接返回 ErrSyncConflict
	//
	// 返回值:pushed 是实际上传的文件数(delta),0 表示无变化.
	Push(ctx context.Context, localDir string, policy ConflictPolicy) (pushed int, err error)

	// IsAvailable 检查后端是否可用(凭证有效,网络可达,工具存在等).
	//
	// 精妙之处(CLEVER): fileStore 在每次 shouldPull/shouldPush 前调用此方法.
	// NoopSyncAdapter 永远返回 false,使 fileStore 在无同步需求时完全跳过同步逻辑,
	// 零 overhead.同时允许后端在运行时动态上线(如网络恢复后返回 true).
	IsAvailable() bool
}

SyncAdapter 是记忆同步的可插拔后端接口.

接口设计原则:

1. 操作目录而非单文件--后端(git,HTTP)天然是批量操作, 逐文件接口会丢失原子性保证.
2. 不感知记忆格式--SyncAdapter 只传输 .md 文件, 不解析 frontmatter,不懂 Memory.Entry,保持职责分离.
3. 凭证/认证由实现者管理--接口不传 token, GitSyncAdapter 用 SSH key,HTTPSyncAdapter 用 Bearer header, 引擎不存任何凭证.

升华改进(ELEVATED): 早期实现没有接口抽象, 直接在函数内调用 Anthropic API(硬编码 URL + OAuth). 我们通过接口解耦,同一 fileStore 可在 CLI/SDK/API 模式下使用完全不同的后端, 无需改引擎代码. 替代方案:<像 TS 那样在 memory 包内内置 HTTP sync> - 否决:耦合特定 API server,无法用于私有部署,测试需要 mock HTTP.

Shape: synchronous callback. Engine (at configured sync triggers) calls Push / Pull synchronously; the adapter talks to the remote backend (git / HTTP / Notion / custom) and returns.

形态: 同步回调. 引擎在配置的同步触发点同步调 Push / Pull; adapter 对接 远端后端 (git / HTTP / Notion / 自定义) 然后返回.

type SyncConfig ¶

type SyncConfig struct {
	// ConflictPolicy 是写冲突时的处理方式.
	ConflictPolicy ConflictPolicy

	// PullPolicy 是自动 Pull 的触发条件.
	PullPolicy PullPolicy

	// PullTTL 是 PullWithTTL 策略的冷却时间.
	// 仅在 PullPolicy == PullWithTTL 时有效,其他策略忽略此字段.
	PullTTL time.Duration
}

SyncConfig 组合了冲突策略和 Pull 策略,描述 fileStore 的完整同步行为.

func APISyncConfig(ttl time.Duration) SyncConfig

func DefaultSyncConfig() SyncConfig

type TextScorer ¶

type TextScorer struct{}

TextScorer 基于文本相似度的评分器(默认实现). 算法:Jaccard-like + token 权重 + 子串匹配. 这是从原始包级函数 Score() 重构而来,算法完全不变.

func (s *TextScorer) Name() string

func (s *TextScorer) Score(query string, header *MemoryHeader) float64

type Type ¶

type Type string

Type 是记忆类型枚举.

const (
	TypeUser      Type = "user"      // 用户画像
	TypeFeedback  Type = "feedback"  // 行为指导
	TypeProject   Type = "project"   // 项目上下文
	TypeReference Type = "reference" // 外部指针
)

type WeightedScorer ¶

type WeightedScorer struct {
	Scorer RelevanceScorer
	Weight float64
}

WeightedScorer 将评分器和权重绑定在一起.