NornWeave 소개: AI 에이전트에게 자체 이메일 인박스 제공
Source: Dev.to
내가 계속 마주친 문제
AI 에이전트에게 이메일을 읽고 보낼 수 있는 능력을 부여하려고 할 때마다 같은 벽에 부딪혔습니다. 표준 이메일 API는 트랜잭션 전송을 위해 설계되었습니다—환영 이메일을 보내고, 영수증을 전송하고, 끝. 설계상 상태를 유지하지 않습니다.
하지만 에이전트는 컨텍스트가 필요합니다. 다음을 알아야 합니다:
- “고객이 세 번째 전 메시지에서 뭐라고 했나요?”
- “이것이 새로운 대화인가, 아니면 진행 중인 스레드의 일부인가?”
- “HTML 잡동사니와 서명 블록을 제외한 실제 내용은 무엇인가?”
같은 스레딩 로직, 같은 HTML‑to‑text 변환, 같은 웹훅 핸들러를 반복해서 작성하고 있었습니다. 그래서 NornWeave를 만들어 한 번에 해결하고 같은 문제에 직면한 모든 사람과 공유했습니다.
NornWeave란?
NornWeave는 AI 에이전트를 위해 특별히 제작된 오픈‑소스, 자체‑호스팅 Inbox‑as‑a‑Service API입니다. 원시 이메일 위에 두 개의 레이어를 추가합니다:
| Layer | Description |
|---|---|
| Stateful Layer | 가상 인박스, 대화 스레드, 전체 메시지 히스토리 |
| Intelligent Layer | HTML → Markdown 파싱, 자동 스레딩, 의미 검색 |
에이전트는 복잡한 웹훅과 HTML 파싱에 얽매이지 않고 깔끔한 REST API 또는 MCP(Model Context Protocol)를 통해 이메일을 소비합니다.
하이라이트
📬 에이전트를 위한 가상 인박스
각 에이전트마다 고유한 이메일 주소가 할당됩니다. 필요에 따라 원하는 만큼 생성하세요:
curl -X POST http://localhost:8000/v1/inboxes \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Support Agent", "email_username": "support"}'이제 하나의 인박스를 공유하고 제목줄로 필터링할 필요가 없습니다. 각 에이전트가 자신의 대화를 소유합니다.
🧵 자동 스레딩
NornWeave는 이메일 헤더(In-Reply-To, References, Message-ID)를 사용해 관련 메시지를 자동으로 스레드로 묶습니다. 스레드를 가져오면 LLM 친화적인 형식으로 제공됩니다:
{
"id": "th_123",
"subject": "Re: Pricing Question",
"messages": [
{ "role": "user", "author": "bob@gmail.com", "content": "How much is it?", "timestamp": "..." },
{ "role": "assistant", "author": "agent@myco.com", "content": "$20/mo", "timestamp": "..." }
]
}이제 “이메일 체인을 파싱하고 누가 뭐라고 했는지 파악한다”는 작업이 필요 없습니다. 이미 처리되어 있습니다.
🧹 깔끔한 콘텐츠, 불필요한 내용 제거
수신된 HTML 이메일은 깔끔한 Markdown으로 변환됩니다. 서명, 면책조항, 인용된 답장 블록 등이 제거되어 에이전트가 실제 메시지만 볼 수 있습니다.
🔌 MCP 통합
NornWeave는 Claude, Cursor 및 기타 MCP 호환 클라이언트와 직접 연결되는 MCP 서버를 제공합니다.
| 도구 | 기능 설명 |
|---|---|
create_inbox | 새 이메일 주소 프로비저닝 |
send_email | 이메일 전송 (Markdown → HTML 자동 변환) |
search_email | 관련 메시지 검색 |
wait_for_reply | 답장이 도착할 때까지 블록 (실험적) |
MCP 클라이언트에 다음과 같이 설정합니다:
{
"mcpServers": {
"nornweave": {
"command": "nornweave-mcp",
"args": ["--api-url", "http://localhost:8000"]
}
}
}이제 에이전트가 “내 인박스를 확인해줘”라고 말하면 실제로 수행됩니다.
📧 사용 중인 이메일 제공업체와 호환
| 제공업체 | 발송 | 수신 |
|---|---|---|
| Mailgun | ✅ | ✅ |
| AWS SES | ✅ | ✅ |
| SendGrid | ✅ | ✅ |
| Resend | ✅ | ✅ |
웹훅 URL만 설정하면 NornWeave가 나머지를 처리합니다.
아키텍처 (조금의 노르스 신화)
| 모듈 | 이름 | 목적 |
|---|---|---|
| 저장 레이어 | Urdr (The Well) | PostgreSQL/SQLite 어댑터 |
| 수집 엔진 | Verdandi (The Loom) | 웹훅 처리, HTML → Markdown 변환, 스레드화 |
| 아웃바운드 레이어 | Skuld (The Prophecy) | 이메일 전송, 속도 제한 |
| API 게이트웨이 | Yggdrasil | FastAPI 라우트, 모든 것을 연결 |
| MCP 리소스 | Huginn (Thought Raven) | AI 에이전트를 위한 읽기 작업 |
| MCP 도구 | Muninn (Memory Raven) | AI 에이전트를 위한 쓰기 작업 |
원시 이메일 스트림은 우물에서 나오는 물처럼 들어옵니다. 직조기는 이를 일관된 스레드로 엮어냅니다. 여러분의 에이전트는 깨끗하고 구조화된 소스로부터 마십니다.
시작하기
# Clone the repo
git clone https://github.com/DataCovey/nornweave.git
cd nornweave
# Copy environment config
cp .env.example .env
# Start with Docker
docker compose up -d
# Run migrations
docker compose exec api alembic upgrade head또는 uv를 사용한 로컬 개발을 선호한다면:
make install-dev
make migrate
make dev전체 문서는 여기에서 확인할 수 있습니다.
What’s Next?
나는 지금 공개적으로 이 프로젝트를 진행하고 있기 때문에 로드맵이 공개돼 있어. 내가 생각하고 있는 내용은 다음과 같아:
- 더 나은 첨부 파일 처리 – PDF와 문서를 텍스트로 추출해 에이전트가 활용하도록
- 예약 전송 – “내일 오전 9시에 답장”
- 에이전트 핸드오프 패턴 – 봇에서 사람으로 원활하게 에스컬레이션
- 다양한 벡터 검색 옵션 – pgvector를 넘어서는 옵션
하지만 솔직히 말해서, 당신이 필요로 하는 것이 무엇인지 듣고 싶어. 이메일을 다루는 에이전트를 만들고 있다면 가장 어려운 부분은 뭐야? 무엇이 당신의 작업을 더 쉽게 만들 수 있을까? 프로젝트 형태를 잡는 데 자유롭게 의견을 주세요.
NornWeave는 Apache 2.0 라이선스를 따르며, 저장소는 .
공개적으로 빌드하는 건 조금 무섭지만 동시에 흥미롭기도 해. 나는 한동안 이 작업에 몰두했었고, 이제 비슷한 문제를 해결하는 다른 사람들에게도 공감될 수 있는지 확인할 수 있게 되었어.
AI 에이전트에게 이메일을 통한 커뮤니케이션 능력을 부여한다면, NornWeave가 내가 겪었던 여러 골칫거리를 덜어주길 바라. 아직 당신의 필요에 딱 맞지 않다면—왜 그런지 알려줘. 나는 귀 기울이고 있어.
읽어줘서 고마워. 즐거운 위빙 되세요. 🧶