atomicstrata/atomicmemory

에이전트 및 애플리케이션을 위한 검사 가능한 휴대용 시맨틱 메모리 (semantic memory).

AtomicMemory는 AI 코드가 이미 실행되고 있는 곳에 임베드(embed)할 수 있는 메모리 계층입니다. 직접적인 SDK 호출, CLI, MCP 서버, 프레임워크 어댑터(framework adapter) 또는 호스트 플러그인(host plugin)을 통해 컨텍스트(context)를 캡처하고, 이전 상호작용에 기반하여 생성 결과물을 접지(ground)하며, 세션 전반에 걸쳐 지식을 전달합니다. 지원되는 경우 로컬 우선(Local-first) 방식을 취하며, 편리한 경우 호스팅(hosted) 방식을 사용하며, 애플리케이션을 다시 작성하지 않고도 나중에 선택을 변경할 수 있도록 설계되었습니다.

대부분의 메모리 제품은 AI가 사용자에 대해 무엇을 믿을지를 결정하는 계층을 호스팅된 블랙박스(black box)에 맡기라고 요구합니다. AtomicMemory는 정반대의 입장을 취합니다. 인터페이스는 휴대 가능해야 하고, 엔진은 검사 가능(inspectable)해야 하며, 메모리 시스템은 사실이 변경될 때 스스로를 수정할 수 있어야 합니다.

이 저장소(repository)는 AtomicMemory JavaScript / TypeScript 패키지, 프레임워크 어댑터, 호스트 플러그인 및 공개 스모크 테스트(smoke tests)를 위한 공개적인 진실의 원천(source of truth)입니다.

문서(Docs): docs.atomicstrata.ai

현장 노트: AI 메모리 산업은 블랙박스 문제를 안고 있습니다.

AtomicMemory v66은 발표된 경쟁사들과 동일한 방법론을 적용했을 때 BEAM-100K, BEAM-1M 및 LoCoMo10에서 성능/비용 면에서 앞서고 있습니다. BEAM-10M에서는 가장 강력하게 발표된 Mem0-new 결과와 대등한 수준을 보이며, Hindsight 규모의 시간적 검색(temporal retrieval)은 알려진 미개척 영역(open frontier)으로 남아 있습니다.

벤치마크 (Benchmark)	AtomicMemory v66	위치 (Position)	비용/질문 (Cost/Q)	샘플 (Sample)
BEAM-100K lenient	0.7375	Hindsight의 0.75와 대등	$1.26	n=80
BEAM-1M lenient	0.6625	성능/비용 선두; Mem0 논문 대비 +0.022	$0.083	n=80
BEAM-10M lenient	0.4875	Mem0-new의 0.486과 대등	$0.081	n=80
LoCoMo10 GPT-4o-mini binary	0.8396	성능/비용 선두; Mem0 논문 대비 +0.171	$0.066	n=1540

이러한 결과는 AtomicMemory가 실제 애플리케이션에서 중요한 저비용 운영 프로필을 유지하면서도, 보고된 각 카테고리에서 발표된 상한선(ceiling)에 도달하거나 그에 근접했음을 보여줍니다. 재현성 아티팩트(Reproducibility artifacts)와 하네스(harness) 세부 사항은 벤치마크 자료와 함께 공개될 예정입니다.

이식성 (Portable): 직접적인 SDK 호출, CLI, MCP 서버, 프레임워크 어댑터(adapters), 그리고 호스트 플러그인(host plugins)에 의해 소비되는 단일 메모리 프로토콜입니다. 동일한 메모리 저장소(memory store)가 캡처(capture) 또는 검색(retrieval) 의미론을 재구현할 필요 없이 LangGraph 에이전트, Claude Code 세션, 그리고 커스텀 Vercel AI 애플리케이션에 모두 서비스를 제공합니다.

SDK-불가지론적 (SDK-agnostic): 모든 어댑터는 동일한 SDK를 기반으로 구축됩니다. 어댑터는 편의를 위한 도구일 뿐, 제약 요소가 아닙니다. 언제든지 SDK로 직접 내려가서 동일한 데이터, 인덱스(indexes), 그리고 검색 동작을 유지할 수 있습니다.

검사 가능성 (Inspectable): 코어(Core)는 오픈 소스이며, 셀프 호스팅(self-hostable)이 가능합니다. 또한 불투명한 호스팅 기반의 의견(hosted opinion)이 아닌, 명시적인 변이(mutation) 결정(decisions)을 중심으로 구축되었습니다.

수정 인지 (Correction-aware): 메모리는 단순히 추가(append)하고 회상(recall)하는 것이 아닙니다. 실제 제품에는 사용자가 마음을 바꿀 때를 대비하여 대체(supersession), 명확화(clarification), 삭제(deletion), 무작위 동작(no-op) 결정, 계보(lineage), 그리고 신뢰 민감형 수정(trust-sensitive revision) 기능이 필요합니다.

모델 표면 이식성 (Model-surface portable): SDK를 통해 애플리케이션이 메모리 백엔드(backends)를 교체할 수 있습니다. 코어는 임베딩(embeddings), 추출(extraction), 변이(mutation), 재순위화(reranking), 검색 패키징(retrieval packaging), 그리고 평가(evaluation)를 분리하여 메모리 엔진이 특정 모델 버전(model vintage)에 고착되지 않도록 합니다.

로컬 또는 호스팅, 당신의 선택 (Local or hosted, your choice): 코어 엔진은 개인정보 보호가 중요한 워크로드(workloads)를 위해 로컬에서 실행됩니다. 호스팅 프로필은 적절한 곳에서 사용할 수 있으며, 아래 패키지 매트릭스(package matrix)에 명확하게 표시됩니다. 두 방식 사이에 기능적 격차(capability cliff)는 존재하지 않습니다.

종속성 없음 (No lock-in): 패키지 API는 안정적이며 유의적 버전(semver) 규칙을 준수합니다. 직접적인 SDK 사용, 어댑터, 그리고 호스트 플러그인 간의 마이그레이션은 문서화되어 있으며 데이터를 다시 인제스트(re-ingesting)할 필요가 없습니다. 메모리 저장소의 소유권은 귀하에게 있습니다.

Core— 내구성이 있는 컨텍스트 (durable context), 시맨틱 검색 (semantic retrieval), 메모리 변이 (memory mutation), 그리고 Postgres/pgvector 저장소를 갖춘 Docker 배포 가능 메모리 백엔드입니다.SDK— 프로바이더 인터페이스 (provider interfaces), 저장소 헬퍼 (storage helpers), 로컬 임베딩 (local embeddings), 그리고 시맨틱 검색 프리미티브 (semantic search primitives)를 포함하며, 백엔드에 종속되지 않는 (backend-agnostic) TypeScript 클라이언트 인터페이스입니다.CLI 및 MCP— 설정, 진단, 캡처, 검색 및 컨텍스트 패키징을 위한 커맨드 라인(CLI) 및 MCP 인터페이스입니다.Framework adapters— Vercel AI SDK, OpenAI Agents SDK, LangChain, LangGraph, 그리고 Mastra를 위한 통합 패키지입니다.Host plugins— Claude Code, OpenClaw, Hermes, Codex, 그리고 Cursor와 같은 에이전트 호스트를 위한 패키지 및 매니페스트 (manifest) 인터페이스입니다.Public validation— 설치 경로, 문서, 패키지 상태를 동기화하는 패키지 메타데이터 체크, 스모크 컨트랙트 (smoke contracts), 그리고 기여자 안전 CI 게이트 (contributor-safe CI gates)입니다.

SDK는 이식성 계약 (portability contract)입니다. 애플리케이션은 특정 메모리 벤더 대신 타입이 지정된 인터페이스 (typed interface)와 프로바이더 경계 (provider boundary)에 의존합니다. Core는 그 자리를 차지할 수 있는 엔진입니다. 자체 호스팅이 가능하고, 감사가 가능하며, 단순 추가 전용 회상 (append-only recall)이 아닌 리비전 (revision)을 중심으로 설계되었습니다.

• 호스팅되는 AtomicMemory 서비스 인프라가 아닙니다.
• 릴리스 오케스트레이션 (release orchestration) 또는 마켓플레이스 운영 시스템이 아닙니다.
• Python SDK가 아닙니다. Python 패키지는 현재 별도의 리포지토리와 PyPI 메타데이터에 유지됩니다.
• 벤치마크 연구 리포지토리가 아닙니다. 재현 가능한 벤치마크 스위트 (benchmark suites)와 로우 에발 하네스 (raw eval harnesses)는 공개 아티팩트 (public artifacts)로 게시될 준비가 될 때까지 이 공개 모노레포 (monorepo) 외부에 존재합니다.
• 패키지 수준 README의 대체물이 아닙니다. 패키지별 설정은 여전히 packages/, adapters/, 그리고 plugins/ 아래에 있습니다.

우리는 마케팅용 주장이 아닌, 지원 가능한 성능 수치를 제시합니다. 위의 헤드라인 결과는 일치하는 방법론 하에서의 벤치마크 점수입니다. 지연 시간 (latency), recall@k, 그리고 스케일 엔벨로프 (scale-envelope)에 대한 주장은 이를 생성하는 데 사용된 연결된 벤치마크, 하드웨어, 데이터셋 및 날짜와 함께 인용되어야만 합니다.

문서에서 지연 시간 (latency) 벤치마크가 연결될 때까지, 이 엔진을 "전형적인 에이전트 코퍼스 (agent corpus) 크기에서 개발자 노트북을 통한 한 자릿수 밀리초 (single-digit-ms) 단위의 로컬 검색을 위해 설계됨"으로 간주하십시오. 이는 설계 목표 (design target)이지 보증 (guarantee)이 아닙니다.

전체 워크스루 (walkthrough)를 보려면 AtomicMemory 퀵스타트 (quickstart)를 참조하십시오.

이 명령어들은 현재 게시된 패키지들을 사용합니다. 아직 공개되지 않은 호스트 플러그인 인터페이스 (plugin surfaces)는 아래의 패키지 매트릭스 (package matrix)에 나열되어 있으며, 메인 설치 경로의 일부가 아닙니다.

# direct SDK
npm install @atomicmemory/sdk
# CLI
...

최소 SDK 형태:

import { MemoryClient } from '@atomicmemory/sdk';
const memory = new MemoryClient({
providers: {
...

최소한의 예제, 환경 설정, 그리고 지원되는 호스트 및 프레임워크의 전체 목록은 아래에 링크된 문서 사이트에 있습니다. 어댑터 (Adapter) 및 플러그인 설치 계약 (install contracts) (설치 유형, 로컬 코어 요구 사항, 호스트 모드 상태)은 각 통합 (integration) 페이지 상단에 표시됩니다.

상태 라벨은 문서 계약을 따릅니다:

published— npm 레지스트리에서 사용 가능하며 지원됨.
implemented, publish pending— 코드가 이 리포지토리 (repo)에 존재하고 로컬에서 작동하지만, 모노레포 (monorepo) 시대의 첫 번째 릴리스는 아직 생성되지 않았음. 해당 행이 published로 바뀌기 전까지는 설치 명령어에 포함하지 마십시오.

coming soon— 공개 소스는 존재하지만, 호스트 설치 경로가 아직 지원되지 않음. 해당 행이 published로 바뀌기 전까지는 설치 명령어에 사용하지 마십시오.

unsupported/planned— 향후 항목을 위해 예약됨.

패키지 (Package)	경로 (Path)	상태 (Status)
@atomicmemory/core	packages/core	published
@atomicmemory/sdk	packages/sdk	published
@atomicmemory/cli	packages/cli	published
@atomicmemory/mcp-server	packages/mcp-server	published

패키지 (Package)	경로 (Path)	상태 (Status)
@atomicmemory/vercel-ai	adapters/vercel-ai	published
@atomicmemory/openai-agents	adapters/openai-agents	published
@atomicmemory/langchain	adapters/langchain	published
@atomicmemory/langgraph	adapters/langgraph	published
@atomicmemory/mastra	adapters/mastra	published

패키지 (Package)	경로 (Path)	상태 (Status)
@atomicmemory/claude-code-plugin	plugins/claude-code	published
@atomicmemory/openclaw-plugin	plugins/openclaw	published
@atomicmemory/hermes-plugin	plugins/hermes	published
@atomicmemory/codex-plugin	plugins/codex	coming soon
@atomicmemory/cursor-plugin	plugins/cursor	coming soon

Codex 및 Cursor 플러그인 소스는 존재하지만, 각 호스트 마켓플레이스 매니페스트 형식이 엔드투엔드로 검증될 때까지는 공개 호스트 설치 경로가 'coming soon' 상태입니다.

표면 (Surface)	위치 (Location)	상태 (Status)
Python SDK (atomicmemory on PyPI)	별도 저장소 (separate repository)	published; 이 모노레포의 일부 아님 (not part of this monorepo)

스켈레톤은 pnpm workspaces와 Turborepo를 태스크 그래프 및 캐시 계층으로 사용합니다. pnpm이 의존성 해결(dependency resolution), 워크스페이스 연결(workspace linking), 패킹을 담당합니다. Turbo가 태스크 순서 지정(task ordering), 캐싱, 영향을 받는 태스크 선택(affected-task selection)을 담당합니다.

# 설치 (pnpm@9.15.4 고정 버전 사용)
pnpm install
# 빌드 / 타입 체크 / 테스트
...

패키지 버전은 하나의 전역 모노레포 버전 대신 릴리스 패밀리(release family)별로 의도적으로 범위가 지정됩니다. @atomicmemory/core와 @atomicmemory/sdk는 독립적으로 이동합니다. 호스트 플러그인은 함께 이동하고, 프레임워크 어댑터는 함께 이동하며, CLI/MCP-server 도구 쌍은 함께 이동합니다:

pnpm check:version-families # 드리프트에 대한 CI 가드

릴리스 버전 증가(Release bumping), 공개 동기화(public sync), 레지스트리 게시 준비는 ops 저장소에서 담당합니다. 이 소스 저장소는 패키지 메타데이터와 버전-패밀리 일관성 검사에 집중하도록 유지하십시오.

Build, test, lint, 및 docs-contract는 Turborepo의 태스크 그래프 (task graph)를 통해 실행됩니다.
Typecheck는 패키지 스크립트가 tsc --noEmit을 사용하기 때문에 캐시 출력 (cache outputs)을 선언하지 않습니다.

부수 효과가 발생하는 체크 항목들 (pack-dry-run, public-integration-smoke, repo-hygiene, code-health, 그리고 security-compliance)은 cache: false 태스크 또는 루트 노드 스크립트를 통해 항상 재실행됩니다. package-metadata는 직접적인 루트 체크이므로 항상 현재 패키지 매니페스트 (package manifests)를 읽습니다.

CI 레인 (CI lanes)은 동일한 Turbo 태스크에 대해 얇은 별칭 (thin aliases)을 사용합니다:

pnpm run ci:affected # 영향받은 패키지에 대한 build / typecheck / lint; 독립적인 패키지에 대한 tests
pnpm run ci:code-health # fallow/code-health 커버리지
pnpm run ci:pack-dry-run # pack-dry-run, affected-only
...

ci:affected와 ci:pack-dry-run은 일반적인 PR에 대해 Turbo의 --affected 필터를 사용합니다. 전체 릴리스-그린 (release-green) 검증은 접두사가 없는 스크립트를 실행하므로, 필요한 검증 범위가 영향 분석 (affected detection)에 의해 좁혀지지 않습니다. 코어 패키지의 DB 기반 테스트 스위트 (test suite)는 서비스 프로비저닝 (service provisioning)이 필요하므로 의도적으로 일반적인 affected 레인에서 제외되어 있습니다. 하지만 build, typecheck, lint, metadata, 그리고 pack 검증은 공용 CI에서 여전히 @atomicmemory/core를 포함합니다.

패키지별 명령 (pnpm --filter @atomicmemory/sdk run build 등)은 packages/, adapters/, 그리고 plugins/에 있는 패키지들에 대해 작동합니다.

패키지별 변경 로그 (changelogs)는 각 패키지 옆에 위치합니다. 패키지 간 및 모노레포 (monorepo) 롤업 변경 사항은 CHANGELOG.md에 기록됩니다.

packages/ core, sdk, cli, mcp-server
adapters/ framework integrations (Vercel AI, OpenAI Agents, LangChain, LangGraph, Mastra)
...

릴리스 오케스트레이션 (Release orchestration), 마켓플레이스 운영, 민감한 서비스 설정, 그리고 로컬 머신 경로는 의도적으로 이 저장소의 일부가 아닙니다.

워크플로, 브랜치 보호 규칙 (branch protection rules), 그리고 풀 리퀘스트 (pull request)가 거치는 공용 CI 레인에 대해서는 CONTRIBUTING.md를 참조하십시오.

AI 코딩 에이전트 (AI coding agents)는 또한 AGENTS.md를 읽어야 합니다. CLAUDE.md 및 GEMINI.md

각자의 CLI (Command Line Interface)가 동일한 공개 지침을 가리키도록 합니다.

보안 정책 (Security policy), 지원되는 버전, 그리고 기밀 보고 채널은 SECURITY.md에 문서화되어 있습니다.

의심되는 취약점은 공개 이슈 (public issue)를 생성하는 대신 기밀로 보고해 주시기 바랍니다.

Apache License 2.0 — LICENSE를 참조하세요.