Agent write-back — AI가 만든 결과를 iri에 저장하기

한눈에 보기. AI 에이전트(Claude, Cursor, 사내 봇)가 만든 결과물을 iri에 자동으로 저장하는 기능입니다.

왜 필요한가요. AI가 작업할 때마다 결과를 회사 어딘가에 따로 저장하면 흩어집니다. iri에 저장하면 다음 작업에서 그 결과를 다시 참고할 수 있고, 다른 사람이나 다른 AI 에이전트도 함께 볼 수 있습니다.

언제 쓰나요. AI가 회의록을 정리했을 때, 보고서 초안을 만들었을 때, 코드 리뷰 결과를 정리했을 때, 고객 응답을 작성했을 때. 이 모든 결과를 한 곳에 누적해두면 시간이 지나면서 회사의 자산이 됩니다.

---

개발자용 상세

Agents that only read from iri miss the compounding loop. Write-back is how the knowledge graph improves with every task.

Two write paths

Path	Endpoint / tool	When to use
Lightweight note	POST /api/notes · create_note MCP tool	Quick notes, ad-hoc captures
Structured document	POST /api/documents · create_document MCP tool	Anything an agent produces — flows into the atoms pipeline, versioned

Prefer create_document for agent output. It enforces frontmatter that lets iri version by (agent, task) and lineage by inputs / citations.

For team/project work, pass sphere_slug or sphere_id with the document. The output will appear in that sphere and be included in sphere-scoped briefings on the next retrieval.

Minimum frontmatter

type: analysis          # research | analysis | review | summary | ...
agent: my-agent-v1      # stable identifier
task: pricing-audit-q2  # same agent + task → new version

Optional but strongly recommended:

• inputs: slugs of documents this output is built from
• citations: slugs explicitly referenced in the body
• status: draft / complete / needs_review
• next_steps: suggestions for the next agent

MCP example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_document",
    "arguments": {
      "title": "Q2 pricing tier analysis",
      "body": "## Summary\n...\n## Evidence\n- See [[plans-2025-01]]\n",
      "frontmatter": {
        "type": "analysis",
        "agent": "pricing-bot",
        "task": "pricing-audit-q2",
        "inputs": ["plans-2025-01", "competitive-scan-2025-03"],
        "status": "complete",
        "citations": ["plans-2025-01"],
        "next_steps": ["Validate with finance", "Roll into Q3 plan"]
      }
    }
  }
}

What happens after POST

1. Validates frontmatter — missing type, agent, or task → 400.
2. Checks rate limit (per workspace + agent). Over → 429 with Retry-After.
3. Inserts the document. Returns {slug, version}.
4. Cron picks up the ingest job (/api/cron/process-ingest) → chunks + embeds.
5. Next cron (/api/cron/process-extraction) → extracts atoms via Haiku.
6. When a human later edits this doc, correction-propagation.ts supersedes the atoms that came from it.

Scoring agent output

src/lib/agent-quality.ts scores each write-back on structural heuristics (has citations, has inputs, reasonable length, internal consistency). Scores show up on the workspace activity feed so you can see which agents produce high-signal work.

Don't

• Don't skip citations. Uncited claims still produce atoms, but with lower confidence.
• Don't change agent or task between re-runs you want versioned — a new pair creates a new document, not a version.
• Don't dump >500KB bodies. Hard cap.