airsync
Collaborative memory system for AI agents and teams. Three-layer architecture (INBOX → PUBLISHED → ARCHIVED) ensures only high-quality knowledge reaches the shared team memory.
How do I install this agent skill?
npx skills add https://github.com/aircury/ai-framework --skill airsyncIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a managed memory system for agents to store and retrieve knowledge. It includes security best practices such as a gated review process for new information and explicit instructions to avoid storing sensitive data.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Airsync Memory Workflow
Purpose
Airsync is a managed memory system where AI agents and human developers collaboratively build a shared knowledge base. Unlike traditional knowledge bases where everything is searchable immediately, Airsync uses a gated lifecycle to prevent low-quality content from contaminating team-wide search.
The Three Layers
| Layer | Visibility | TTL | Purpose |
|---|---|---|---|
| INBOX | Explicit only | 14 days | Raw captures awaiting review |
| PUBLISHED | Default search | Permanent | Vetted, high-quality knowledge |
| ARCHIVED | Explicit only | Permanent | Retired or obsolete content |
Key Principle: Writing to the knowledge base ≠ Making it searchable.
Required Workflow
1. Retrieve Context First
Before making architectural decisions or implementing changes:
memory_search(
query="your search terms",
memory_kind="best_practice", # optional filter
tags_any=["relevant", "tags"] # optional filter
)
- Default search only returns PUBLISHED memories
- Use
layers=["PUBLISHED", "ARCHIVED"]to include archived content - Use
layers=["INBOX"]only when explicitly reviewing pending memories
2. Produce Output With Traceability
- Cite memory IDs for major decisions: "Based on mem_01hz3kp8x2a5mv7b..."
- If memories conflict, prefer higher quality scores and newer timestamps
- Note when you're overriding documented best practices
3. Capture Learnings (INBOX)
When you discover something worth remembering:
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"],
}
)
Important: All proposals go to INBOX, not directly to PUBLISHED. They won't appear in default searches until promoted.
4. Quality Self-Check Before Proposing
The quality score (0.0-1.0) is computed automatically:
| Criterion | Points |
|---|---|
| Title > 10 chars | +0.20 |
| Content > 50 chars | +0.20 |
| Has memory_kind | +0.15 |
| Scope = project/team | +0.15 |
| ≥2 tags | +0.15 |
| Content > 200 chars | +0.15 |
Minimum 0.5 required for promotion. Improve your entry if quality is low.
Memory Kinds
| Kind | Use For | Example |
|---|---|---|
best_practice | Validated approaches that work | "Keep framework modules aligned with the selected architecture boundaries" |
learning | Insights from experience | "Discovered that batching reduces API calls by 80%" |
observation | Noted patterns without full validation | "Seems like Qdrant queries are faster with pre-filtering" |
note | General documentation | "API rate limits are 1000 req/min" |
model | Mental models or frameworks | "The CAP tradeoff in distributed systems" |
Tool Reference
Write Operations
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)
Read Operations
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.
Content Quality Guidelines
DO Capture
- Root cause + fix patterns applicable beyond this task
- Architectural decisions with clear rationale
- Validated runbooks and operational commands
- Repeated pitfalls and how to avoid them
- Team-wide conventions and standards
- Mental models that explain complex systems
DO NOT Capture
- Project-specific implementation details other teams can't reuse
- Debugging sessions without transferable lessons
- Scratch notes or in-progress findings
- Content already in codebase, docs, or prior memory
- Transient observations without context
The Collaboration Test
Before proposing, ask: "Would a developer on a different project benefit from this in 3 months?"
If no → don't propose.
Deduplication
The system prevents duplication at two levels:
1. Exact Duplication (propose phase)
- SHA-256 hash of normalised content
- Rejects identical content within same team
- Returns existing memory ID on conflict
2. Semantic Duplication (promote phase)
- Vector similarity > 0.95 threshold
- Checked against PUBLISHED layer only
- Suggests merge instead of promotion
Best Practice: Search before proposing. If similar content exists, enhance it rather than creating a duplicate.
Example Workflows
Adding a New Best Practice
# 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)
Reviewing Pending Memories
# 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")
Configuration
Environment variables:
| Variable | Default | Description |
|---|---|---|
AIRSYNC_TEAM_ID | "default" | Default team for all operations |
AIRSYNC_INBOX_TTL_DAYS | 14 | Days before INBOX expires |
AIRSYNC_DEDUP_THRESHOLD | 0.95 | Semantic similarity threshold |
AIRSYNC_MIN_QUALITY_FOR_PUBLISH | 0.5 | Minimum quality for promotion |
AIRSYNC_DEFAULT_SEARCH_LAYERS | "PUBLISHED" | Default layers for search |
Safety Rules
- Never store secrets - No credentials, tokens, or personal data
- Never fabricate - Don't invent prior knowledge when search returns nothing
- Cite your sources - Use source_refs for traceability
- Prefer promotion over direct publish - All entries should pass through INBOX
- Archive obsolete content - Don't let outdated knowledge pollute search
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/aircury/ai-framework/airsync">View airsync on skillZs</a>