airsync

Airsync メモリーワークフロー

目的

Airsync は、AI エージェントと人間の開発者が共同で共有ナレッジベースを構築する管理型メモリシステムです。すべてをすぐに検索できる従来のナレッジベースとは異なり、Airsync ではゲート付きライフサイクルを採用し、品質の低いコンテンツがチーム全体の検索結果を汚染するのを防ぎます。

3 つのレイヤー

レイヤー	表示範囲	TTL	目的
INBOX	明示的な指定のみ	14 days	レビュー待ちの未加工データ
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"],
    }
)

重要：すべての提案は、直接 PUBLISHED に追加するのではなく、INBOX に送られます。昇格されるまでデフォルトの検索結果には表示されません。

4. 提案前に品質を自己チェックする

品質スコア（0.0-1.0）は自動的に計算されます：

基準	ポイント
タイトルが 10 文字を超える	+0.20
内容が 50 文字を超える	+0.20
memory_kind が設定されている	+0.15
scope = project/team	+0.15
タグが 2 つ以上	+0.15
内容が 200 文字を超える	+0.15

昇格には最低 0.5 が必要です。品質が低い場合は、エントリーを改善してください。

---

メモリの種類

種類	用途	例
best_practice	有効性が確認されたアプローチ	「フレームワークのモジュールは、選択したアーキテクチャ境界に沿った状態に保ちます」
learning	経験から得た知見	「バッチ処理により API 呼び出しが 80% 削減されることを発見しました」
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 か月後にこれを役立てられるだろうか？」

いいえ → 提案しません。

---

重複排除

このシステムは、2 つの段階で重複を防ぎます：

1. 完全な重複（propose 段階）

• 正規化されたコンテンツの SHA-256 ハッシュ
• 同じチーム内の同一コンテンツを拒否します
• 競合時には既存のメモリ ID を返します

2. 意味的な重複（promote 段階）

• ベクトル類似度のしきい値 > 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. 古くなったコンテンツはアーカイブする - 古い知識が検索結果に混入しないようにします