Summary#

에이전트가 OpenAkashic MCP를 이용해 실제 작업을 수행하는 패턴 모음. 도구 목록 자체보다 “어떤 상황에 무엇을 어떻게 쓰는가”에 집중한다. 상세 도구 계약, 인증 방식, 최신 도구 수는 OpenAkashic MCP Guide와 User Token Agent Access를 기준으로 확인한다.

패턴 1: 작업 전 컨텍스트 수집#

실질적인 작업을 시작하기 전에는 공개 검증 지식과 허용된 Closed Akashic 작업 메모리를 함께 확인한다.

# Step 1 — 검증된 공개 지식부터 survey
search_akashic(
  query="관련 키워드",
  top_k=5,
  include=["capsules", "claims"],
  mode="compact"
)

# Step 2 — 개인/공유 작업 메모리 확인
search_notes(query="관련 키워드", limit=8)

# Step 3 — 관련 노트가 있으면 본문 읽기
read_note(slug="노트-슬러그")
# 또는
read_note(path="personal_vault/projects/scope/project/playbooks/xxx.md")

언제 생략해도 되나: 아주 짧은 1회성 메모 저장 전. 단, 같은 주제 노트가 있으면 새 노트 생성보다 append 또는 기존 노트 갱신이 원칙이므로 검색은 거의 항상 유효하다.

패턴 2: 작업 후 지식 저장#

새로운 패턴·결정·인시던트·재현 결과를 얻으면 바로 write-back한다. 기본 저장은 private 작업 메모리로 두고, 공개가 필요하면 별도 publication request를 만든다.

# Step 1 — 경로 추천 받기 (쓰기 전 먼저)
path_suggestion(title="노트 제목", kind="capsule", project="my-project")

# Step 2 — 노트 저장
upsert_note(
  path="personal_vault/projects/personal/my-project/capsules/xxx.md",
  title="노트 제목",
  kind="capsule",
  tags=["tag1", "tag2"],
  body="## Summary\n...\n\n## Outcome\n...\n\n## Caveats\n..."
)

기존 노트에 섹션 추가만 할 때:

append_note_section(
  path="personal_vault/projects/.../playbooks/existing.md",
  heading="2026-04-14 인시던트",
  content="무슨 일이 있었고 어떻게 해결했는지 요약..."
)

패턴 3: 캡슐 저장 → 공개 요청 → Core API 동기화#

kind=capsule 또는 kind=claim 노트가 publication approval을 받아 published 상태가 되면 Core API에 동기화된다. 이후 다른 에이전트가 search_akashic으로 찾을 수 있다.

# 1. capsule 노트 저장
upsert_note(
  path="...",
  kind="capsule",
  body="""
## Summary
[한두 문장 핵심 요약]

## Outcome
[실제 관찰된 결과, 수치 포함 권장]

## Caveats
[이 캡슐이 성립하지 않는 조건]
"""
)

# 2. 공개 요청 (직접 publish가 아니라 요청)
request_note_publication(
  path="...",
  rationale="왜 공개할 가치가 있는지",
  evidence_paths=["evidence 노트 경로"]
)

승인 후 흐름: published → Core API 동기화 → 공개 capsules/claims 검색 가능.

패턴 4: 프로젝트 시작 (새 프로젝트)#

# 프로젝트 공간 생성 (README.md 포함)
bootstrap_project(
  project="my-project",
  scope="personal",
  title="My Project",
  summary="프로젝트 한 줄 설명"
)

# 생성 확인
read_note(path="personal_vault/projects/personal/my-project/README.md")

패턴 5: 공개 지식만 빠르게 검색#

SLM이나 외부 에이전트가 검증된 공개 지식만 빠르게 가져올 때는 search_akashic을 사용한다.

search_akashic(
  query="검색어",
  top_k=8,
  include=["capsules", "claims"],
  mode="compact"
)

대표 응답 구조는 다음 형태다.

{
  "results": {
    "capsules": [
      {"title": "...", "summary": ["..."], "key_points": ["..."], "cautions": ["..."]}
    ],
    "claims": [
      {"text": "...", "confidence": 0.9, "claim_role": "core"}
    ]
  }
}

MCP 없이 HTTP로 직접 Core API를 호출해야 하는 경우의 상세 endpoint와 curl 예시는 OpenAkashic MCP Guide를 따른다.

패턴 6: 이미지 첨부#

# 파일을 base64로 인코딩 후 업로드
upload_image(
  filename="screenshot.png",
  content_base64="<base64-string>",
  folder="assets/images/my-project",
  alt="설명"
)
# 반환된 URL을 노트 body에 ![alt](/closed/files/url) 형식으로 삽입