Anansi: 자가 호스팅 바이템포럴 메모리 엔진

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

Anansi는 조직 내부의 대화·문서·티켓을 받아 구조화된 엔티티 그래프와 합성 프로필을 생성하는 자가 호스팅 메모리 엔진으로, POST /v1/ingest와 GET /v1/context 두 호출로 통합할 수 있다. 각 엣지는 사실의 유효 시점과 시스템이 이를 기록한 시점을 분리해 저장하는 바이템포럴 모델을 사용해 과거 상태와 변경 시점을 근거와 함께 재구성할 수 있다. 검색은 Postgres에서 pgvector와 BM25를 결합한 하이브리드 쿼리로 수행되며, 로컬 Ollama나 nomic-embed-text 같은 경량 임베딩을 이용해 약식으로 5분 내에 실습해볼 수 있다.

섹션별 상세

Anansi는 조직의 대화·문서·티켓 같은 기존 출력물을 받아 구조화된 메모리와 엔티티 그래프를 생성하는 자가 호스팅 메모리 엔진으로 설계되어 있다. 사용자는 POST /v1/ingest로 컨텐츠를 큐에 넣고 GET /v1/context로 합성된 프로필과 관련 청크를 얻을 수 있으며 이 두 API 호출만으로 실무 대화 흐름에 통합할 수 있다. 이 설계는 임베딩과 합성 작업을 비동기화해 응답 경로 지연을 줄이고, 합성된 결과를 바로 시스템 프롬프트에 붙여 쓰기 쉬운 출력 형식을 제공한다.

Anansi 라이브 데모 GIF: 합성된 프로필과 엔티티 그래프, 그리고 'Why did the team switch to GraphQL?' 질의에 증거 인용을 포함해 응답하는 흐름을 보여준다. — Screenshot화면은 네 건의 합성된 슬랙 메시지를 ingest한 뒤 API가 자동으로 프로필과 엔티티 그래프를 생성하고 질의에 대해 관련 근거를 인용하는 동작을 시연한다. 특히 'as of' 토글로 시스템이 그 시점에 무엇을 알고 있었는지와 실제 사실이 언제인지(두 시간 축)를 동시에 비교하는 인터랙션을 시각적으로 확인할 수 있다. 이 이미지는 데모의 end-to-end 처리(ingest→synthesize→query→citation)를 한눈에 검증할 수 있게 해 실무 적용 가능성을 판단하는 데 유용하다.

근거

Anansi의 기본 사용 흐름은 두 API 호출로 이루어지며 POST /v1/ingest와 GET /v1/context가 핵심 엔드포인트다. — 초반 TL;DR 섹션과 Quickstart 단계, API 표에서 두 엔드포인트의 역할(ingest=202 반환, context=합성된 프로필 반환)을 확인할 수 있다.

빠른 시작은 Docker Compose로 로컬 스택을 띄우고 임베딩 백엔드를 연결하는 세 가지 경로(A: 호스트의 Ollama, B: Nomic 호스티드 임베딩를 이용한 hybrid, C: Compose 내부의 Ollama)를 제시해 초기 설치를 5분 안에 끝내도록 최적화되어 있다. ingest는 202를 즉시 반환하고 임베딩은 백그라운드에서 이루어지므로 임베딩이 준비되지 않은 상황에서도 키워드 기반 하이브리드 검색으로 결과를 일부 확보할 수 있다. nomic-embed-text(274MB)는 임베딩에 필요한 최소 이미지이고, 합성용 모델(llama3.1:8b 등)은 별도 풀을 권장한다.

근거

로컬 빠른 시작은 Docker Compose와 nomic-embed-text(274MB), 또는 호스트의 Ollama를 활용하면 약 5분 내에 동작하는 인스턴스를 만들 수 있다. — Quickstart의 'Start the stack'와 'Give it something to embed' 섹션에 구체적 이미지 크기(274 MB)와 옵션별 소요 시간을 밝히고 있다.

핵심 데이터 구조는 엔티티 그래프이며, 모든 엣지는 두 개의 시간 축(valid time과 recorded/knowledge time)을 가진다. 이 bi-temporal 모델은 사실이 실제로 언제 유효했는지와 시스템이 그 사실을 언제 알았는지를 분리해 저장하므로 과거 상태 재구성이나 변경 시점 질의가 정확하게 가능하다. 구현은 Postgres 기반으로 pgvector와 BM25를 단일 SQL에서 결합해 검색하고, 증거는 append-only 원장(ledger)에 인용문 형태로 남겨 신뢰등급과 상태를 추적하도록 설계되어 있다.

근거

엔티티 그래프의 각 엣지는 valid time(사실이 성립한 시점)과 recorded/knowledge time(시스템이 그 사실을 기록한 시점)이라는 두 개의 독립적 시간 축을 가진다. — lib/db/schema.ts와 lib/ai/query-engine.ts 구현 설명 및 'Two clocks' 소제목에서 bi-temporal 구현 세부가 기술되어 있다.

검색과 저장은 별도의 벡터 DB 없이 Postgres에서 완결되며, 검색은 pgvector 코사인 유사도와 ts_rank BM25를 reciprocal rank fusion으로 합친 단일 트랜잭셔널 쿼리로 동작한다. 이로 인해 벡터 DB 운영 부담이 사라지고 일관된 트랜잭션 모델 안에서 인제스트·청킹·검색이 유지된다. 또한 ingest → embed → synthesize → retrieve 루프와 SDK들이 함께 제공되어 실무 통합이 단순화된다.

bash

curl -X POST http://localhost:3000/v1/ingest \
  -H "Authorization: Bearer $ANANSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId":"user_123","content":"User is building a voice agent. Prefers TypeScript. Team of 4.","sourceType":"conversation"}'

로컬에 키를 발급한 뒤 POST /v1/ingest로 사용자의 텍스트를 보낼 때 쓰는 명령이다. 응답은 202를 반환하고 실제 임베딩 작업은 백그라운드 큐에서 처리되기 때문에 호출자 경로에 지연을 남기지 않는다. 즉시 202을 받고 이후 GET /v1/context로 결과를 조회하면 관련 벡터·청크·프로필을 얻을 수 있다.

bash

curl -G http://localhost:3000/v1/context \
  -H "Authorization: Bearer $ANANSI_API_KEY" \
  --data-urlencode "userId=user_123" \
  --data-urlencode "q=what is the user building?"

GET /v1/context는 이미 합성된 프로필(static/dynamic)과 관련 청크를 반환하는 주된 읽기 경로이다. 임베딩이 아직 반영되지 않은 경우에도 키워드 검색을 섞어 하이브리드 방식으로 어느 정도 결과를 제공해 빈 응답을 피한다. 질의별로 반환된 similarity 점수를 통해 의미적 유사도와 검색 상태를 확인할 수 있다.

보안·운영 측면에서는 로컬·hybrid·cloud 세 가지 배포 모드를 명확히 구분하고 로컬 모드에서는 외부 키를 설정하면 서버가 기동을 거부하도록 강제하여 데이터 유출 실수를 방지하는 설정이 포함되어 있다. API 키는 HMAC-SHA256 해시로 저장되고 커넥터 토큰은 AES-256-GCM으로 암호화되며, SSRF 방어와 프롬프트 인젝션·PII 마스킹 규칙이 인제스트 경로에 통합되어 있다. 다만 SOC2·ISO27001·HIPAA 같은 인증은 제공되지 않으므로 준수 요건이 있는 조직은 추가 검토가 필요하다.

javascript

import AnansiMemory from "anansi-memory";
const memory = new AnansiMemory({ apiKey: process.env.ANANSI_API_KEY, baseUrl: "http://localhost:3000" });
await memory.ingest({ userId: "user_123", content: "User is building a voice agent. Prefers TypeScript. Team of 4.", sourceType: "conversation" });
const ctx = await memory.context({ userId: "user_123", q: "what is the user building?" });
const systemPrompt = `You are a helpful assistant.

${memory.formatForPrompt(ctx)}`;

TypeScript SDK를 통해 로컬 인스턴스에 연결하고 메모리를 인제스트·조회하는 예제이다. baseUrl을 로컬 API로 지정해야 호출이 호스티드 서비스가 아닌 사용자의 인스턴스로 향한다는 점이 중요하다. SDK는 /v1 API를 얇게 감싼 클라이언트 역할을 하므로 자체 로직은 거의 없고 formatForPrompt로 바로 시스템 프롬프트에 넣기 쉬운 형태를 만든다.

오픈코어 모델을 채택해 엔진 핵심은 MIT 라이선스로 누구나 자체 배포할 수 있지만 SSO·SCIM·감사·거버넌스 같은 엔터프라이즈 표면은 LICENSE-EE로 분리해 상업적 라이선스를 요구한다. 자체 호스팅 시에는 기본적으로 엔터프라이즈 플랜 권한이 활성화되어 추가 설정 없이 모든 기능을 쓸 수 있으나 운영 중 과금·업그레이드 연동이 필요하면 Stripe 또는 ANANSI_DEFAULT_PLAN으로 직접 구성해야 한다. 이 분리는 코드 가시성을 유지하면서 상업적 운영 기능을 별도 허가로 묶는 전형적인 오픈코어 패턴이다.

용어 해설

바이-템포럴 모델(Bi-temporal model): — 사건의 실제 발생 시점(valid time)과 시스템이 이를 기록한 시점(knowledge time)을 독립적으로 보관하는 시계열 모델로, 언제 사실이 성립했는지와 언제 시스템이 그 사실을 알았는지를 별도로 조회할 수 있게 해준다.
엔티티 그래프(Entity graph): — 문서·대화에서 추출한 엔티티와 관계를 노드와 엣지로 구조화한 그래프이며, 각 엣지에 시간 축과 출처 근거를 연결해 질문 시 관련 실체와 근거를 신속하게 재구성하는 핵심 데이터 구조이다.
하이브리드 검색(pgvector + BM25)(Hybrid retrieval (pgvector + BM25)): — 벡터 유사도(pgvector)와 전통적 BM25 랭킹을 reciprocal rank fusion으로 결합해 의미적 유사성과 키워드 신호를 동시에 반영하는 단일 SQL 쿼리 기반 검색 방식이다.
인제스트·컨텍스트 API(Ingest / Context API): — POST /v1/ingest로 데이터를 비동기 큐에 넣어 임베딩과 청킹을 수행하고 GET /v1/context로 이미 합성된 프로필과 관련 청크를 즉시 반환해 시스템 프롬프트로 바로 사용할 수 있게 하는 API 패턴이다.
오픈코어 라이선스(MIT + EE)(Open-core license (MIT + EE)): — 엔진 핵심은 MIT로 누구나 자체 배포할 수 있으나 SSO·SCIM·감사·거버넌스 같은 엔터프라이즈 표면은 LICENSE-EE로 별도 상용 라이선스가 필요하도록 분리한 라이선스 모델이다.

기술

Postgres와 Redis를 데이터·작업 큐로 활용하고 pgvector로 벡터를 저장하며 ts_rank BM25와 reciprocal rank fusion으로 하이브리드 검색을 구현한다.
Ollama를 로컬 인퍼런스·임베딩 백엔드로 사용하거나 nomic-embed-text 같은 경량 임베딩 이미지를 가져와 임베딩 처리 파이프라인을 구성한다.
TypeScript SDK(anansi-memory), Python SDK, LangChain 통합(anansi-langchain)과 Vercel AI SDK 미들웨어를 통해 애플리케이션 레이어에 빠르게 연결할 수 있도록 클라이언트를 제공한다.

활용 사례

제품·운영팀의 내부 위키와 채팅 로그가 불일치할 때 문서화된 절차(runbook)와 관찰된 실무 행동의 차이를 시점별로 찾아내어 언제 정책이 바뀌었는지 근거와 함께 밝히는 내부 지식 감사.
에이전트가 고객이나 직원의 과거 발언을 근거로 결정을 내려야 하는 시나리오에서, 시스템이 언제 어떤 정보를 알았는지를 분리해 조회해 실수성 발언(후입력된 정보로 인한 잘못된 재구성)을 줄이는 장기 대화형 메모리.
자가호스팅 요건이 강한 조직에서 모든 컨텐츠를 로컬에 남기고 싶을 때, 로컬 Ollama와 Compose만으로 완성 가능한 임베딩·합성 파이프라인을 운영하는 내부 플랫폼 통합.