오픈 소스 프로젝트 #100: OpenMemory — AI 에이전트를 위한 진정한 인지 메모리 엔진

서론

"벡터 데이터베이스는 무엇이 말해졌는지를 기억합니다. OpenMemory는 그것이 무엇을 의미했는지, 언제 일어났는지, 어떤 느낌이었는지, 그리고 왜 중요한지를 기억합니다."

이 글은 "하루에 하나의 오픈 소스 프로젝트(One Open Source Project a Day)" 시리즈의 100번째 기사입니다. 오늘의 프로젝트는 LLM 애플리케이션과 AI 에이전트를 위한 셀프 호스팅 인지 메모리 엔진인 OpenMemory입니다.

LLM은 설계상 상태가 없는(stateless) 특성을 가집니다. 대부분의 "메모리" 솔루션은 사실 RAG (Retrieval-Augmented Generation) 파이프라인을 위장한 것에 불과합니다: 텍스트를 청크(chunk)로 나누고, 이를 벡터 스토어(vector store)에 임베딩(embed)하며, 유사도에 따라 검색합니다. 이들은 메모리의 유형(이것이 사실인지, 사건인지, 기술인지, 아니면 감정인지?)을 이해하지 못하며, 시간(이것이 지난달에도 사실이었는가?)을 추적하지 못하고, 중요도(이것이 저것보다 더 관련이 있는가?)를 모델링하지 못하며, 연관 관계(이 두 가지는 서로 관련이 있다)를 유지하지 못합니다.

OpenMemory의 논지: AI 에이전트는 마케팅 문구에 "메모리"라는 단어가 들어간 벡터 데이터베이스가 아니라, 실제 메모리 시스템을 가질 자격이 있습니다.

학습 내용

• 5개 섹터 메모리 모델: 에피소드(episodic), 의미(semantic), 절차(procedural), 감정(emotional), 성찰(reflective) — 각 모델의 의미와 서로 다른 속도로 감쇠(decay)하는 방식
• HMD v2 아키텍처: 계층적 메모리 분해(Hierarchical Memory Decomposition)가 작동하는 방식
• 웨이포인트 연관 그래프(Waypoint association graph): 단일 최강 경로(single-strongest-path) 그래프와 복합 점수 공식
• 시계열 지식 그래프(Temporal knowledge graph): valid_from / valid_to 및 사실의 진화
• RAG 및 벡터 데이터베이스와의 근본적인 차이점
• 세 가지 운영 모드: 임베디드 SDK, 독립형 서버, MCP 인터페이스

사전 요구 사항

• LLM 에이전트에 대한 기본 이해
• LangChain, CrewAI 또는 유사한 에이전트 프레임워크에 대한 익숙함
• 벡터 임베딩(vector embeddings) 및 코사인 유사도(cosine similarity)에 대한 기본 이해

프로젝트 배경

개요

OpenMemory는 HMD (Hierarchical Memory Decomposition) v2 아키텍처를 기반으로 구축된 오픈 소스 인지 메모리 엔진입니다. 이는 LLM 애플리케이션과 AI 에이전트를 위해 지속 가능하고 구조화된 메모리를 제공합니다.

이것은 벡터 데이터베이스 (Vector Database) 래퍼가 아닙니다. 클라우드 메모리 API의 대체제도 아닙니다. 설계 철학은 다음과 같습니다: 메모리는 데이터베이스가 아니라 — 감쇠 (Decay), 강화 (Reinforcement), 연관 (Association), 그리고 시간적 차원 (Temporal dimensions)을 가진 동적인 시스템입니다.

이 프로젝트는 CaviraOSS에 의해 유지 관리되며, Python SDK, Node.js SDK, REST API 서버, VS Code 확장 프로그램, 그리고 네이티브 MCP 서버를 제공합니다.

저자 / 팀

• 조직 (Organization): CaviraOSS
• 주요 언어 (Primary language): TypeScript/Node.js (서버), Python (SDK)
• 라이선스 (License): Apache 2.0
• VS Code 확장 프로그램 (VS Code Extension): marketplace.visualstudio.com

프로젝트 통계 (Project Stats)

• 📄 라이선스 (License): Apache 2.0
• 🐍 PyPI: openmemory-py
• 📦 npm: openmemory-js
• 🧩 통합 (Integrations): LangChain, CrewAI, AutoGen, Streamlit, MCP, VS Code

기능 (Features)

작동 방식

전통적인 RAG 메모리 (벡터 DB):
"사용자는 땅콩 알레르기가 있고, 밤에 코딩하는 것을 선호하며, 생산성을 느낀다"
    → 하나의 임베딩 벡터 (Embedding vector)
...

사용 사례 (Use Cases)

1. 장기 대화 어시스턴트 (Long-term conversation assistants): 컨텍스트를 반복하지 않고도 세션 전반에 걸쳐 사용자의 선호도, 습관 및 이력을 기억합니다.
2. 에이전트 프레임워크 메모리 계층 (Agent framework memory layer): CrewAI, AutoGen, LangGraph 에이전트를 위한 공유 장기 메모리 저장소 역할을 합니다.
3. 지식 노동자 도구 (Knowledge worker tools): GitHub, Notion, Google Drive 콘텐츠를 수집합니다. 에이전트는 "지난주 디자인 결정 사항이 무엇이었지?"라고 물을 수 있습니다.
4. 코딩 어시스턴트 (Coding assistants): 세션 전반에 걸쳐 코드 선호도, 프로젝트 컨텍스트, 기술 스택 선택 사항을 유지합니다.
5. 감정 인식 애플리케이션 (Emotion-aware applications): 감정 섹션에 감성 (Sentiment)을 별도로 저장하여, 사실적 메모리 검색 (Factual memory retrieval)을 오염시키는 것을 방지합니다.

빠른 시작 (Quick Start)

Python SDK (로컬 SQLite, 설정 불필요):

pip install openmemory-py

from openmemory.client import Memory

mem = Memory()
...

Node.js SDK:

npm install openmemory-js

import { Memory } from "openmemory-js"

const mem = new Memory()
...

LangChain 통합 (LangChain integration):

from openmemory.integrations.langchain import OpenMemoryChatMessageHistory

history = OpenMemoryChatMessageHistory(memory=mem, user_id="u1")
...

OpenAI 인터셉터 (interceptor) 패턴:

mem = Memory()
client = mem.openai.register(OpenAI(), user_id="u1")
# 이후의 모든 chat.completions.create 호출은 자동으로 메모리를 저장/검색합니다
...

외부 데이터 소스 인제스션 (Ingesting):

# GitHub 리포지토리 인제스션
github = mem.source("github")
await github.connect(token="ghp_...")
...

사용 가능한 커넥터 (connectors): github, notion, google_drive, google_sheets, google_slides, onedrive, web_crawler

MCP 통합 (Claude Code / Cursor):

# Claude Code
claude mcp add --transport http openmemory http://localhost:8080/mcp

// Cursor .mcp.json
{
  "mcpServers": {
...

사용 가능한 MCP 도구 (tools): openmemory_query, openmemory_store, openmemory_list, openmemory_get, openmemory_reinforce

5가지 메모리 섹터 (Memory Sectors)

섹터 (Sector)	의미 (Meaning)	감쇠율 (Decay Rate)	가중치 (Weight)
episodic	사건과 경험 (무엇이, 언제 일어났는지)	0.015 (빠름)	1.2
...

감쇠 공식 (Decay formula): salience × e^(-decay_lambda × days_since_last_seen)

감쇠는 24시간마다 실행됩니다. 가중치가 0.05 미만인 웨이포인트 (Waypoint) 링크는 7일마다 제거(pruned)됩니다.

심층 분석 (Deep Dive)

HMD v2 아키텍처

입력 콘텐츠 (Input content)
    ↓
섹터 분류기 (Sector Classifier)
...

웨이포인트 연관 그래프 (The Waypoint Association Graph)

이것은 OpenMemory를 벡터 데이터베이스 (vector databases)와 차별화하는 핵심적인 아키텍처 설계 중 하나입니다:

메모리 A ──0.85──▶ 메모리 B
(가장 강력한 단일 링크만 유지됨)

메모리가 추가될 때, 시스템은 가장 유사한 기존 메모리 하나(코사인 유사도 (cosine similarity) ≥ 0.75)를 찾아 단방향 웨이포인트 (Waypoint) 링크를 생성합니다. 섹터 간(Cross-sector) 링크는 양방향입니다.

쿼리 시점에는 상위 K개(top-K) 벡터 검색 후, 1-홉 그래프 탐색 (1-hop graph traversal)을 통해 웨이포인트를 통해 연결된 메모리까지 결과를 확장합니다. 웨이포인트를 탐색할 때마다 해당 가중치는 +0.05만큼 증가하며 (최대 1.0), 자주 함께 회상되는 메모리들은 시간이 지남에 따라 더 강력한 링크를 형성하게 됩니다.

실질적인 효과: 메모리와 의미론적으로 가깝지 않은 쿼리라도, 연결된 메모리의 점수가 높다면 해당 메모리를 불러올 수 있습니다. 이는 순수한 유사도 검색 (Similarity Search)이 아닌, 창발적인 연상 회상 (Emergent Associative Recall)을 만들어냅니다.

시계열 지식 그래프 (Temporal Knowledge Graph)

OpenMemory는 시간을 일급 시민 (First-class dimension) 차원으로 취급합니다:

# 2021년에 사실(fact) 추가
POST /api/temporal/fact
{
...

지원되는 작업:

• valid_from / valid_to 진실 구간 (Truth windows)
• 특정 시점 쿼리 ("2022년 하반기에 CompanyX의 CEO는 누구였나요?")
• 변경 탐지 (사실이 언제 뒤집혔는가?)
• 엔티티 타임라인 재구성

성능 데이터

10만 개(100k)의 메모리 기준 (WAL 모드를 사용하는 SQLite):

작업	지연 시간 (Latency)
메모리 추가	80-120 ms (임베딩 제공자에 따라 다름)
...

저장 용량 추정치:

• 단일 메모리: ~4-6 KB (모든 섹터 벡터 포함)
• 10만 개 메모리: ~500 MB
• 100만 개 메모리: ~5 GB

SaaS 대안들과의 비교

차원	OpenMemory	Supermemory	OpenAI Memory
호스팅	셀프 호스팅 (Self-hosted)	클라우드 전용	클라우드 전용
...

비용 차이는 API 과금 방식의 임베딩 호출 대신 로컬 임베딩 (Ollama, BGE, E5)을 실행한다는 점과, 클라우드 인프라 마진이 없다는 점에서 발생합니다.

타 시스템으로부터의 마이그레이션

OpenMemory는 기존 메모리 데이터를 가져오기 위한 마이그레이션 도구를 제공합니다:

cd migrate

# Mem0로부터 마이그레이션
...

데이터베이스 스키마 (Database Schema)

핵심 SQLite 스키마는 아키텍처를 투명하게 보여줍니다:

-- 현저성 (Salience) 및 감쇠 (Decay) 파라미터가 포함된 메모리 레코드
CREATE TABLE memories (
  id TEXT PRIMARY KEY,
...

리소스 (Resources)

공식 링크

• 🌟 GitHub: CaviraOSS/OpenMemory
• 📦 PyPI: openmemory-py
• 📦 npm: openmemory-js
• 🔌 VS Code Extension: openmemory-vscode
• 📄 아키텍처 문서: ARCHITECTURE.md (리포지토리 내)

요약 (Summary)

OpenMemory의 기여는 "메모리 (memory)"를 마케팅 용어가 아닌 진지한 엔지니어링 문제로 다룬다는 점에 있습니다.

대부분의 개발자가 "AI 메모리"를 말할 때, 그것은 검색 증강 생성 (Retrieval-Augmented Generation, RAG) — 즉, 벡터를 저장하고 유사도에 따라 검색하는 것을 의미합니다. OpenMemory의 입장은 이것은 검색 (search)이지 메모리가 아니라는 것입니다. 진정한 메모리 시스템은 어떤 정보가 사실인지 아니면 감정인지, 그것이 최근의 것인지 아니면 역사적인 것인지, 그것이 오늘날에도 여전히 유효한지, 그리고 그것이 다른 무엇과 연관되어 있는지를 알아야 합니다.

5개 섹터 모델 (five-sector model), 웨이포인트 그래프 (Waypoint graph), 시계열 지식 그래프 (temporal knowledge graph), 그리고 복합 점수 산정 (composite scoring)은 단순히 복잡성을 위한 복잡성이 아닙니다. 이는 인간의 메모리가 실제로 작동하는 방식의 뚜렷한 차원들을 매핑한 것입니다.

세션 간 메모리 (cross-session memory)가 필요한 에이전트 애플리케이션을 구축하는 개발자들에게, OpenMemory는 오늘날 사용 가능한 가장 아키텍처적으로 일관된 오픈 소스 옵션 중 하나입니다: 셀프 호스팅 (self-hosted), 로컬 우선 (local-first), 프레임워크 불가지론적 (framework-agnostic), 설명 가능하며 (explainable), 성능 예측이 가능합니다 (performance-predictable). 통합하는 데는 단 세 줄의 코드면 충분하며, 필요할 때는 완전한 서버 모드를 제공합니다.

_ PrimeSkills를 탐색해 보세요 — 실제 기업 워크플로우에 대해 검증된 AI 에이전트 및 스킬이 큐레이션된 마켓플레이스입니다. 과장 없이, 실제로 작동하는 것들만 제공합니다. _

_ 더 많은 통찰력과 흥미로운 제품을 보려면 저의 개인 사이트를 방문하세요. _