asurada-0.2.0 is not a library.

Asurada

사용자와 함께 성장하는 AI 메모리·인지 데몬.

asurada 는 macOS 백그라운드 데몬으로 동작하며 도메인 무관 인지 레이어 역할을 합니다. 어떤 도구든 brain.db 를 통해 Asurada 와 협력하여 사용자에게 advice / memory / TTS 를 제공할 수 있습니다.

무엇을 하는가

Asurada 는 외부 런타임(Claude Code 등)과 사용자 사이에 자리잡아 사용자의 개인성을 견고하게 보존합니다. Claude Code 가 어떻게 진화하든 Asurada 가 안정적으로 통제합니다.

3계층 규칙 모델

강도	통제 채널	적용 시점
선호 (preference)	메모리 주입	UserPromptSubmit hook → 컨텍스트 prepend
원칙 (principle)	Hook 차단	PreToolUse hook → ask/deny 결정
맥락 (context)	파일 생성	CLAUDE.md / `.claude/skills/` 자동 생성

자율 진화 루프

사용자 prompt → 신호 누적 → 패턴 인지 → advice 큐 →
사용자 confirm → intent 또는 하네스 진화 → Claude 행동 변경 → 다음 prompt

5분 간격으로 데몬이 자동 스캔. 사용자는 asurada advice list (또는 Devist Dashboard) 에서 제안만 검토하면 됩니다.

특징

로컬 우선 — ~/.asurada/brain.db (SQLite + FTS5) 가 단일 진실 + Postgres 양방향 sync
BYOK — 사용자 본인의 Postgres + ElevenLabs API 키. 자격증명을 binary 에 절대 baked-in 안 함.
Hook 기반 통제 — Claude Code 의 hook 메커니즘 위에 구축. Skill/Plugin 변화 무관.
Intent + Adapter 패턴 — 의도(intent)는 외부 형식 비종속. Adapter 가 현재 Claude Code 형식으로 컴파일.
셀프 호스팅 진화 — Asurada 가 자기 진화를 위해 자기 advice 시스템을 사용.
단일 인격, 다중 사용자 — 한 Asurada 가 여러 사용자를 user_id 별 컨텍스트로 응대.
TTS — ElevenLabs 통합 (어드바이스 음성 출력, 향후 양방향 대화).

설치

# Homebrew
brew install webchemistcorp/asurada/asurada

# Cargo
cargo install asurada

# 소스
git clone https://github.com/WebchemistCorp/asurada && cd asurada && cargo install --path .

빠른 시작

Asurada 는 사용자 본인의 Postgres 에 데이터를 저장합니다 (BYOK).

# 1) 첫 설치 마법사 — Postgres URL 입력, user.id 발급
asurada init

# 2) Postgres 측 스키마 마이그레이션 (한 번)
psql "$URL" -f migrations/supabase/0001_init.sql
psql "$URL" -f migrations/supabase/0002_intents_harnesses.sql

# 3) 5문항 cold start — 초기 intent seed
asurada onboard

# 4) Claude Code hook 자동 등록
asurada hook install

# 5) intent → CLAUDE.md / gates / skill 컴파일
asurada intent compile

# 6) 데몬 등록 (자동 sync + 자동 패턴 스캔)
./scripts/install-launchd.sh

# 7) (선택) TTS
asurada config set tts.api_key 'sk_...'
asurada tts voices && asurada tts on

명령어

라이프사이클

명령	설명
`asurada init`	brain.db + config 초기화
`asurada onboard`	5문항으로 초기 intent seed
`asurada serve [--port]`	데몬 시작 — HTTP API + sync + 자동 패턴 스캔
`asurada path`	경로 확인
`asurada config show / path / set`	설정 조회 / 변경

개인성 (Intent — 사용자 의도)

명령	설명
`asurada intent add --strength <s> "<text>"`	수동 추가 (preference / principle / context)
`asurada intent list / get <id>`	조회
`asurada intent archive <id>`	보관
`asurada intent compile [--dry-run]`	활성 intent → Claude Code 형식 컴파일

자율 인지 (관찰 → 제안)

명령	설명
`asurada hook install / uninstall / status`	Claude Code hook 등록
`asurada signals recent / summary`	누적 행동 신호
`asurada pattern scan / propose`	군집 인지 → advice 큐로 surface
`asurada advice list / get / promote / dismiss`	advice 처리

하네스 (자동 생성)

명령	설명
`asurada harness propose / apply`	패턴 → agent + skill + references 4종 파일 생성
`asurada harness list / get <id>`	메타 + 사용량 + 진화 로그
`asurada harness evolve-scan [--propose]`	사용 vs 교정 비율 → 진화 advice

관리

명령	설명
`asurada sync push / pull / run`	수동 sync (events + memories + advice + projects + intents + harnesses)
`asurada admin normalize-events`	events 의 project 케이스 정규화 (마이그레이션)
`asurada tts on / off / status / voices / speak / test`	TTS

아키텍처

                      Claude Code (외부 런타임 — 빠르게 진화)
                             ▲ ▲ ▲
                  hook       │ │ │ files
                 (PreToolUse,│ │ │ (CLAUDE.md / .claude/skills/agents)
              UserPromptSub.)│ │ │
                             │ │ │
   ┌─────────────────────────┴─┴─┴───────────────────────┐
   │  asurada 데몬                                       │
   │  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  │
   │  │ 신호 도출    │→ │ 패턴 인지     │→│ advice 큐  │  │
   │  │ (intervention│  │ (redo cluster,│  │ (셀프호스팅)│  │
   │  │  redo, use) │  │  evolution)   │  │           │  │
   │  └─────────────┘  └──────────────┘  └────────────┘  │
   │         │                              │            │
   │         ▼                              ▼            │
   │  ┌──────────────────┐        ┌──────────────────┐   │
   │  │ Intent 저장      │        │ 사용자 confirm   │   │
   │  │ (DB)             │←──────│ (CLI / Dashboard)│   │
   │  └──────────────────┘        └──────────────────┘   │
   │         │                                            │
   │         ▼ Adapter (RuntimeAdapter trait)             │
   │  ┌──────────────────────────────────────────────┐    │
   │  │ ClaudeCodeAdapter — intent → 현재 Claude Code │    │
   │  │ 형식 (CLAUDE.md / gates.json / skill 파일)   │    │
   │  └──────────────────────────────────────────────┘    │
   │                                                      │
   │  HTTP API (/healthz /memories /harnesses /advice)    │
   │  + 자동 패턴/진화 스캔 (5분 간격)                    │
   └──────────────────────────────────────────────────────┘
                  │                       │
                  ▼                       ▼
            ~/.asurada/brain.db    사용자의 Postgres
            (WAL, 다중 프로세스)     (BYOK Supabase 등)
                  ▲
                  │ INSERT events
            소비자 도구 (Devist 등)

Intent → Adapter 패턴

규칙은 의도(intent) 로 저장 — 외부 런타임 형식에 비종속
RuntimeAdapter trait 가 현재 Claude Code 형식으로 컴파일
Anthropic 이 hook/skill 스펙을 바꾸면 Adapter 만 교체. 규칙 본체 보존.

책임 경계

Asurada 는 인지 + 통제 레이어 — 도메인은 소비자가 정의한다.

영역	Asurada 담당
메모리 저장 / 분류 / 검색	✅
사용자 행동 신호 도출	✅
패턴 인지 + advice 자동 제안	✅
하네스 자동 생성 + 진화	✅
Claude Code hook 통제 (preference/principle/context)	✅
Intent 저장 + Adapter 컴파일	✅
양방향 sync (brain.db ↔ Postgres)	✅
도메인별 이벤트 정의	❌ (소비자)
사용자 데이터 저장소 호스팅	❌ (사용자 본인 Postgres)

통합 가이드 (소비자 도구 작성용)

~/.asurada/config.toml 의 [user].id 를 user_id 로 사용
~/.asurada/brain.db 의 events 테이블에 INSERT (WAL multi-process safe)
Asurada 가 자동으로 Postgres sync, 패턴 인지, advice 생성까지 처리
결과는 advice 테이블에서 읽기 (또는 HTTP /advice 엔드포인트)
하네스 메타는 harnesses 테이블 (/harnesses 엔드포인트)

스키마: migrations/supabase/0001_init.sql, migrations/supabase/0002_intents_harnesses.sql.

asurada 0.2.0