airsync

Airsync 记忆工作流

目的

Airsync 是一个托管式记忆系统，AI Agent 和人类开发者可在其中协作构建共享知识库。与所有内容都可立即搜索的传统知识库不同，Airsync 采用门控生命周期，防止低质量内容影响团队范围内的搜索。

三个层级

层级	可见性	TTL	用途
INBOX	仅显式访问	14 天	等待审核的原始记录
PUBLISHED	默认搜索	永久	经过审核的高质量知识
ARCHIVED	仅显式访问	永久	已退役或过时的内容

核心原则：写入知识库 ≠ 使其可搜索。

---

必需工作流

1. 首先检索上下文

在做出架构决策或实施更改之前：

memory_search(
    query="your search terms",
    memory_kind="best_practice",  # optional filter
    tags_any=["relevant", "tags"]   # optional filter
)

• 默认搜索只返回 PUBLISHED 记忆
• 使用 layers=["PUBLISHED", "ARCHIVED"] 纳入已归档内容
• 仅在明确审核待处理记忆时使用 layers=["INBOX"]

2. 生成可追溯的输出

• 在重要决策中引用记忆 ID：“基于 mem_01hz3kp8x2a5mv7b...”
• 如果记忆内容冲突，优先选择质量分数较高且时间戳较新的内容
• 说明何时覆盖了已记录的最佳实践

3. 记录经验（INBOX）

发现值得记住的内容时：

memory_propose(
    entry={
        "memory_kind": "best_practice",  # or "learning", "observation", "note", "model"
        "scope": "team",                 # or "project", "agent"
        "author_agent_id": "your-agent-id",
        "title": "Clear outcome-focused title",
        "content": "Detailed explanation with context...",
        "tags": ["architecture", "patterns"],
    }
)

重要：所有提案都应进入 INBOX，而不是直接进入 PUBLISHED。晋升之前，这些内容不会出现在默认搜索结果中。

4. 提案前进行质量自检

质量分数（0.0-1.0）会自动计算：

标准	分数
标题 > 10 个字符	+0.20
内容 > 50 个字符	+0.20
包含 memory_kind	+0.15
范围 = project/team	+0.15
≥2 个标签	+0.15
内容 > 200 个字符	+0.15

晋升至少需要 0.5 分。如果质量较低，请完善条目。

---

记忆类型

类型	用途	示例
best_practice	经验证有效的方法	“让框架模块与所选架构边界保持一致”
learning	从经验中获得的见解	“发现批处理可减少 80% 的 API 调用”
observation	尚未完全验证的观察模式	“使用预筛选时，Qdrant 查询似乎更快”
note	一般文档	“API 速率限制为 1000 req/min”
model	心智模型或框架	“分布式系统中的 CAP 权衡”

---

工具参考

写入操作

memory_propose(entry, team_id?) → MemoryRecord
    Creates a new memory in INBOX. Performs exact deduplication check.
    Returns error if exact duplicate exists in team.

memory_promote(memory_id, team_id?) → PromoteResult
    Moves INBOX memory to PUBLISHED. Requirements:
    - Quality >= 0.5
    - No semantic duplicates (>0.95 similarity) in PUBLISHED
    Returns duplicate_of if similar memory exists.

memory_archive(memory_id, reason, team_id?) → MemoryRecord
    Archives a memory (from any layer). Reasons:
    - "superseded" - replaced by newer content
    - "obsolete" - no longer relevant
    - "incorrect" - contains errors
    - "consolidated" - merged into another memory
    - "expired" - TTL expired (usually automatic)

读取操作

memory_search(query, top_k?, team_id?, layers?, memory_kind?, scope?, tags_any?) → [SearchResult]
    Semantic search with layer-aware filtering.
    Default: only searches PUBLISHED.
    Automatically excludes expired INBOX entries.

memory_get(memory_id, team_id?) → MemoryRecord
    Retrieves any memory by ID (any layer).

memory_list_inbox(team_id?) → [MemoryRecord]
    Lists pending INBOX memories for review.
    Sorted by created_at desc (newest first).

memory_find_duplicates(memory_id, team_id?, threshold?) → DuplicateCheckResult
    Finds exact and semantic duplicates.
    Useful before promotion.

---

内容质量指南

应记录

• 可应用于当前任务之外的根因与修复模式
• 理由明确的架构决策
• 经验证的操作手册和运维命令
• 反复出现的陷阱及其规避方法
• 团队范围内的约定和标准
• 有助于解释复杂系统的心智模型

不应记录

• 其他团队无法复用的项目专属实现细节
• 没有可迁移经验的调试过程
• 草稿笔记或尚在进行中的发现
• 代码库、文档或先前记忆中已有的内容
• 缺少上下文的临时观察

协作测试

提案前，先问自己：“3 个月后，其他项目的开发者会从中受益吗？”

如果不会 → 不要提案。

---

去重

系统在两个层级上防止重复：

1. 完全重复（提案阶段）

• 对规范化内容进行 SHA-256 哈希
• 拒绝同一团队中的重复内容
• 冲突时返回现有记忆 ID

2. 语义重复（晋升阶段）

• 向量相似度超过 0.95 阈值
• 仅与 PUBLISHED 层进行比对
• 建议合并，而不是晋升

最佳实践：提案前先搜索。如果存在相似内容，应完善现有内容，而不是创建重复项。

---

工作流示例

添加新的最佳实践

# 1. Check if it already exists
results = memory_search(
    query="selected architecture framework module boundaries",
    memory_kind="best_practice"
)

# 2. If not found, propose to INBOX
memory = memory_propose(entry={
    "memory_kind": "best_practice",
    "scope": "team",
    "author_agent_id": "claude-opus-4",
    "title": "Keep framework modules aligned with selected architecture boundaries",
    "content": "All framework modules must respect the project's selected architecture boundaries...",
    "tags": ["architecture", "boundaries", "framework"],
})

# 3. When confident, promote to PUBLISHED
memory_promote(memory_id=memory.id)

审核待处理记忆

# List INBOX for review
inbox = memory_list_inbox(team_id="my-team")

for memory in inbox:
    if memory.quality >= 0.5:
        # Check for duplicates first
        dups = memory_find_duplicates(memory.id)
        if not dups.semantic_duplicates:
            memory_promote(memory.id)
        else:
            print(f"Merge candidate: similar to {dups.semantic_duplicates[0].memory.id}")
    else:
        print(f"Low quality ({memory.quality}), needs improvement")

---

配置

环境变量：

变量	默认值	描述
AIRSYNC_TEAM_ID	"default"	所有操作的默认团队
AIRSYNC_INBOX_TTL_DAYS	14	INBOX 过期前的天数
AIRSYNC_DEDUP_THRESHOLD	0.95	语义相似度阈值
AIRSYNC_MIN_QUALITY_FOR_PUBLISH	0.5	提升所需的最低质量
AIRSYNC_DEFAULT_SEARCH_LAYERS	"PUBLISHED"	搜索的默认层级

---

安全规则

1. 绝不存储机密信息 - 不存储凭据、令牌或个人数据
2. 绝不捏造 - 搜索无结果时，不要编造已有知识
3. 注明来源 - 使用 source_refs 以便追溯
4. 优先提升，而非直接发布 - 所有条目都应经过 INBOX
5. 归档过时内容 - 不要让过时知识污染搜索