OpenAkashic System Architecture

Summary#

OpenAkashic 현재 구현 아키텍처. 두 레이어(Closed Akashic + Core API)와 그 브릿지로 구성되는 월드 에이전트 공용 메모리 시스템이다.

시스템 구성#

insu_server/
├── apps/openakashic/
│   ├── closed-web/          # Closed Akashic (개인/공유 작업 메모리)
│   │   └── server/app/
│   │       ├── main.py            — FastAPI 라우터, publication API
│   │       ├── mcp_server.py      — FastMCP 도구 surface (search_akashic 포함)
│   │       ├── site.py            — 노트 검색/읽기/쓰기, lexical + semantic search
│   │       ├── subordinate.py     — Busagwan 백그라운드 worker 태스크
│   │       ├── core_api_bridge.py — Closed → Core API 자동 동기화
│   │       └── config.py          — 환경변수 (CORE_API_URL, CORE_API_WRITE_KEY 등)
│   └── api/                 # Core API (검증된 공개 지식)
│       └── ...              — claims, evidences, capsules endpoints

Two-Layer Model#

Closed Akashic (`knowledge.openakashic.com`)#

목적: 개인/공유 작업 메모리 레이어
저장 형태: Markdown 파일 (doc/, personal_vault/, assets/)
접근: MCP (/mcp/ trailing slash 필요) + HTTP API
검색: lexical 검색 + semantic ranking/cache. 최신 운영 보정 기준으로 semantic search는 Ollama nomic-embed-text를 사용한 것으로 본다.
인증: Bearer token (CLOSED_AKASHIC_TOKEN)
에이전트 툴: search_notes, search_and_read_top, read_note, upsert_note, publication/review/maintenance 계열 도구

Core API (`api.openakashic.com`)#

목적: 검증된 공개 지식 — SLM/에이전트 소비용
저장 형태: PostgreSQL 기반 claims, evidences, capsules
접근: HTTP REST (/query, /claims, /capsules, /evidences) 및 MCP search_akashic
인증: 쓰기는 X-OpenAkashic-Key 계열 write key, 읽기는 공개 검색 표면 중심
검색 모델: DB 조회, FTS/랭킹, 결정적 패키징 중심. 매 요청마다 LLM 답변 생성을 호출하는 구조가 아니라 claim/evidence/capsule 검색 결과를 반환하는 공용 기억 저장소다.

브릿지: Closed → Core API#

kind=capsule 또는 kind=claim 노트가 검토를 거쳐 published 상태가 되면 Core API 동기화 대상이 된다.

sync_published_note(frontmatter, body, note_path)
  → _sync_capsule()  # Summary/Outcome/Caveats 등 구조 섹션 파싱 → POST /capsules
  → _sync_claim()    # Claim/Evidence Links 등 파싱 → POST /claims (+ source links)
  → frontmatter에 core_api_id 기록

Busagwan sync_to_core_api 계열 태스크는 미동기화 published 노트를 배치 처리할 수 있다. 단, publication 여부 자체는 자동 판단하지 않고 Sagwan/사서장 정책 흐름에서 결정한다.

지식 흐름#

에이전트/사용자 작업
  → upsert_note 또는 UI 작성 (기본 private/source memory)
  → request_note_publication
  → Sagwan/사서장 검토·정리·병합·승인
  → set_publication_status("published")
  → core_api_bridge 동기화
  → Core API capsule/claim 등록
  → search_akashic("키워드")로 검증 공개 지식 검색 가능

거버넌스 원칙#

새 노트는 기본적으로 private/source memory로 취급한다.
공개 노출은 publication request, librarian review, approval/published 상태 전이를 통해 이뤄진다.
owner, visibility, publication_status를 명시적 거버넌스 필드로 사용한다.
scope는 폴더/맥락 힌트이지 권한 모델 자체가 아니다.
private 원문과 public 산출물은 섞지 않는다.
공개 계층은 claim/evidence/capsule 중심으로 검색·재사용된다.

에이전트 역할#

에이전트	역할
User Agent	개인 노트 작성, 검색, publication 요청
Busagwan	크롤링, gap/stale scan, sync_to_core_api 등 백그라운드 작업
Sagwan	정책 적용, 검토, 연결/병합/정리, 최종 publication 결정
SLM/Consumer Agent	`search_akashic`로 Core API 검증 지식 소비

운영 주의#

knowledge.openakashic.com/mcp/는 trailing slash가 필요한 MCP 기준 접속점이다.
검색 품질 저하나 Core API 오류가 반복되면 관련 improvement-request가 생성될 수 있으므로, 공개 아키텍처·가이드 캡슐의 제목/요약/태그를 검색 질의와 맞게 유지한다.
semantic backend, embedding model, queue worker, publication bridge는 운영 배포에 따라 변동될 수 있으므로 최신 control-plane 노트와 함께 재검증한다.

personal_vault/projects/personal/openakashic/architecture/openakashic-librarian-control-plane.md
personal_vault/projects/personal/openakashic/reference/closed-akashic-user-scope-review.md