ai-memory

ai-memory™

범용 AI 메모리

ai-memory는 AI 어시스턴트를 위한 영구 메모리 시스템입니다. MCP를 지원하는 모든 AI — Claude, ChatGPT, Grok, Llama 등과 함께 작동합니다. AI가 학습한 내용을 로컬 SQLite 데이터베이스에 저장하고, 회상 시 관련성에 따라 메모리 순위를 매기며, 중요한 지식을 영구 저장소로 자동 승격합니다. 한 번 설치하면 사용하는 모든 AI 어시스턴트가 아키텍처, 선호도, 수정 사항을 영원히 기억합니다.

설치 경로 선택

LLM 백엔드(xAI Grok, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Qwen, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks, LMStudio, vLLM, llama.cpp 서버, 또는 로컬 Ollama)를 구성하시나요? docs/integrations/llm-backends.md를 참조하세요 — MCP 환경 블록 레시피는 설치 경로와 관계없이 동일합니다.

v0.9.0 — 현재 릴리스. 보안 강화 및 코드 리뷰 릴리스: 5개 레인의 적대적 리뷰(#1885–#1935)에서 49개 수정 사항과 소규모 추가 기능 세트가 포함되었습니다. 주요 변경 사항은 보안 기본값 전환입니다: 이제 쓰기 시 에이전트 증명이 기본적으로 필수입니다 (#1751) — 서명되지 않은 MCP memory_store / HTTP POST /api/v1/memories / CLI store은 운영자가 명시적 옵트아웃 AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0을 설정하지 않는 한 attest_level="claimed"로 처리되지 않고 거부됩니다(403 ATTESTATION_FAILED). 이와 함께 필수 훅 존재 적용 게이트가 이제 MCP 쓰기 경로(#1885) 와 HTTP 쓰기 경로(#1924) 모두에서 작동하여, 구성된 필수 훅이 한 표면에서는 건너뛰어지고 다른 표면에서는 그렇지 않을 수 있는 무단 통과 간격을 해소합니다. 강화 작업은 또한 bulk_create 행별 증명 게이팅(#1919)을 닫고, 인바운드 페더레이션 PENDING 승인을 등록된 승인자 게이트를 통해 라우팅하며(#1920), team/unit/org 가시성 범위를 네임스페이스 계층 전체에서 더 이상 과도하게 넓지 않도록 조이고(#1921), skill_register의 folder_path 가져오기를 심볼릭 링크 감옥으로 구성된 루트 아래로 제한합니다(#1923). 새로운 비인수 자격 증명 채널 — AI_MEMORY_STORE_URL / AI_MEMORY_STORE_URL_FILE (0600 파일) — 은 postgres/store 비밀번호를 전역 읽기 가능한 /proc/<pid>/cmdline 및 ps에서 제외합니다(#1927). 추가 기능 작업: parameters_schema + invocation_record (B7-SKILL, #1865)을 포함한 에이전트 작성 스킬 메모리, recall_observations 섀도우 피드백 루프(#1706), 메모리 파생 계보 DAG(memory_lineage, #1859), 그리고 옵트인 벡터 검색 최소 슬라이스(#1005). 표면: 스키마 v78, --profile full에서 101개 MCP 도구(호출 가능 100개 + 항상 켜짐 memory_capabilities 부트스트랩) / --profile core에서 7개, 92개 HTTP 경로 등록(고유 URL 경로 78개), --features sal/sal-postgres 아래 89개 CLI 하위 명령(기본 빌드에서 87개), 9개 유형화된 MemoryLink 관계, 28개 필드 Memory. 데스크톱, 서버, 온디바이스(iOS + Android) 전반에서 두 가지 프로덕션 백엔드(내장 SQLite 및 PostgreSQL + Apache AGE)에서 동일한 API로 실행됩니다. 증명 및 훅 적용 전환을 제외한 모든 것은 v0.8.1에 추가된 사항이며, 이는 보안 기본값을 적용한 주요 변경 사항이므로 업그레이드 전에 검토하십시오. 전체 변경 로그: CHANGELOG.md §"[0.9.0] — 2026-07-08".

v0.8.0 (distributed-coordination) — 이전 릴리스. 이 릴리스는 메모리 기반이 조정 기반이 되는 릴리스입니다. #1709의 분산 조정 메커니즘을 추가합니다: 실제 상태 머신(memory_action_*)을 갖춘 유형화된 액션 DAG, TTL 바운드 단일 소유자 리스(memory_lease_*), Ed25519 서명 신호(memory_signal_*), Ed25519 증명 체크포인트(memory_checkpoint_*), 그리고 고정되어 재생 가능한 루틴(memory_routine_*) — 따라서 이기종 에이전트 집단이 서로를 신뢰할 필요 없이 교대로 작업하고, 작업을 넘기며, 누가 무엇을 말했는지 증명할 수 있습니다. 그 위에 유형화된 인지(Goal/Plan/Step 메모리 종류, lifecycle_state 머신, decomposes_into / depends_on / advances 링크 관계)를 계층화하고, 페더레이션을 보안 기본값으로 강화하며(피어 등록 기본값 ON #1789, 전환별 서명 #1718, 쓰기별 콘텐츠 증명 #1464, 전환 재생 논스 #1805, 아웃바운드 피어 인증서 고정 #1678), 실제로 차단하는 거버넌스를 제공합니다 — Claude Code PreToolUse 훅이 type:command 래퍼로 재작업되어 기반 Refuse이 도구를 실제로 거부합니다(#1811). v0.8.0 릴리스 당시 표면: 스키마 v70, --profile full에서 100개 MCP 도구(호출 가능 99개 + 항상 켜짐 memory_capabilities 부트스트랩) / --profile core에서 7개, 91개 HTTP 경로 등록(고유 URL 경로 78개), 83/85개 CLI 하위 명령, 9개 유형화된 MemoryLink 관계, 27개 필드 Memory. 데스크톱, 서버, 온디바이스(iOS + Android) 전반에서 두 가지 프로덕션 백엔드(내장 SQLite 및 PostgreSQL + Apache AGE)에서 동일한 API로 실행됩니다. 모든 것은 v0.7.0에 추가된 사항이며, 업그레이드 전에 보안 기본값 전환을 검토하십시오. 전체 릴리스 노트: docs/v0.8.0/release-notes.md.

v0.7.0 (attested-cortex) — 이전 릴리스. cortex-fluent 가독성 작업과 ROADMAP §7.3의 전체 v0.7 신뢰 + A2A 범위, 그리고 (운영자 지시 2026-05-09에 따라) 원래 v0.7.1 postgres+AGE 최고 수준 작업, 그리고 그랜드 슬램 이후 출시 준비 웨이브(Batman Forms 1-6 + 7번째 폼 Option-B 기반 + QW-1/2/3 + 조정 보안 스윕)를 통합했습니다. 기반은 더욱 표현력이 풍부해지고(기능 v3, 명명된 로더 도구, 압축된 스키마, Batman MemoryKind 어휘, 페르소나/원자화/다단계 수집 기본 요소) 암호학적으로 신뢰할 수 있게 되었습니다(Ed25519 증명, 사이드체인 트랜잭션, 프로그래밍 가능한 25개 이벤트 훅 파이프라인, 적용된 네임스페이스 상속, V-4 교차 행 서명 이벤트 해시 체인). v0.7.0은 또한 postgres + Apache AGE를 최고 수준의 스토리지 백엔드로 제공합니다 — 실시간 데몬 사용을 위한 ai-memory serve --store-url postgres://…, 두 백엔드 간 스키마 패리티(v0.7.0 릴리스 당시 sqlite + postgres는 논리 스키마 v57로 수렴되었으며, 여기서 CURRENT_SCHEMA_VERSION은 57이었습니다. v0.8.0 릴리스 기반은 이 보조를 스키마 70으로 발전시켰으며, 추가된 v58–v70 조정 + 가시성 테이블이 두 백엔드에 모두 적용되었습니다 — v58–v70 래더에 대해서는 CLAUDE.md §Database 참조) (정식 앵커: sqlite의 경우 src/storage/migrations.rs, postgres의 경우 src/store/postgres.rs); 디스크상 마이그레이션 파일은 migrations/sqlite/0047_v56_list_composite_indexes.sql에서 끝나고 postgres 인프로세스 migrate_v57() 래더 암(파일 이름 카운터는 두 래더 모두 인프로세스 암을 통해 post-v34 델타를 적용하기 때문에 논리 스키마 버전보다 뒤쳐집니다 — v35-v57 내러티브는 docs/MIGRATION_v0.7.md §schema-ladder 참조; v48 #933은 페더레이션 푸시 DLQ 테이블을 추가했습니다; v49 #1025는 archived_memories에 14개의 nullable 열을 추가하여 아카이브 → 복원이 전체 v0.7.0 메모리 형태에 대해 무손실이 되도록 했습니다; v50 #1156은 agent_quotas PRIMARY KEY를 (agent_id)에서 (agent_id, namespace)로 확장하여 단일 에이전트가 여러 네임스페이스에서 작동할 때도 네임스페이스별 K8 할당량이 유지되도록 했습니다 — v50 이전 행은 _global 센티널 네임스페이스로 백필됩니다; v51 #1255 (PR #1296)은 피어 재생 방지 논스가 데몬 재시작 후에도 유지되도록 federation_nonce_cache 테이블을 추가했습니다; v52 #1389은 RFC-0001 memory_capture_turn L4 + recover_from_transcript L2 멱등성을 지원하는 transcript_line_dedup 테이블을 추가하여 턴 사이의 SIGKILL이 후속 재수화 시 중복 메모리를 생성하지 않도록 했습니다; v53 #1418은 memories_au FTS5 동기화 트리거를 (title, content, tags)로만 범위 지정하여 비FTS 열 업데이트 시 불필요한 동기화가 발생하지 않도록 했습니다; v54 #1466은 레거시 NULL 만료 중간/단기 행에 티어 기본 만료를 백필하여 TTL 누출 불멸 행 클래스를 해소했습니다; v55 #1476은 W=2 페더레이션 캐치업 쿼리(updated_at > ? ORDER BY updated_at ASC LIMIT)를 sargable하게 만들고 sqlite idx_memories_updated_at 인덱스를 추가했습니다 — postgres는 memories_updated_at_idx DESC가 이미 Index Scan Backward를 통해 범위 스캔을 제공하므로 새 인덱스를 추가하지 않습니다; v56 #1579은 sargable storage::list 재작성과 쌍을 이루는 복합 목록/아카이브 정렬 인덱스(idx_memories_list_order, idx_memories_ns_list_order, idx_archived_ns_archived_at)를 추가했습니다 — sqlite 측 DDL; postgres migrate_v56() 암은 버전 스탬프 no-op입니다; v57 #1579은 postgres 저장 생성 tsv tsvector 열 + memories_tsv_gin GIN 인덱스를 추가하여 검색/회상 형태가 일치하고 일치된 행당 tsvector를 다시 계산하는 대신 사전 계산된 열에서 순위를 매기도록 했습니다 — 레거시 memories_content_fts 표현식 인덱스는 삭제되고 sqlite 트윈은 FTS5가 이미 인덱스된 텍스트를 구체화하므로 버전 스탬프 no-op입니다), 새로운 ai-memory schema-init CLI 동사, 그리고 6요소 회상 점수 패리티를 제공합니다. v0.6.4 기본 표면은 항상 켜져 있는 두 개의 로더가 추가되어 7개 도구(memory_load_family + memory_smart_load이 원래 5개에 합류)로 증가합니다; --profile full의 런타임 상한은 74개 광고 항목(호출 가능한 메모리 도구 73개 + 항상 켜짐 memory_capabilities 부트스트랩; Profile::full().expected_tool_count()에 대해 검증됨 — src/profile.rs 참조)입니다. 모든 새로운 기능은 추가 사항이며 (신뢰 + postgres 표면의 경우) 옵트인입니다. v0.6.x에서 업그레이드하시나요? docs/MIGRATION_v0.7.md을 먼저 읽으십시오 — 대부분의 v0.6.4 호출자는 동작 변화를 느끼지 못하지만, v0.6.3.1 이전 v0.6.x 사용자는 G1 네임스페이스 상속 수정 사항의 영향을 받습니다. postgres+AGE로 전환하시나요? docs/postgres-age-guide.md 및 docs/migration-v0.7.0-postgres.md를 참조하십시오. 전체 릴리스 노트: docs/v0.7.0/release-notes.md.

v0.6.4 (quiet-tools) — MCP 서버는 5개 도구 기본 표면(memory_store, memory_recall, memory_list, memory_get, memory_search)과 항상 켜져 있는 memory_capabilities 부트스트랩을 제공합니다. 나머지 38개 도구는 --profile graph|admin|power|full 또는 memory_capabilities --include-schema family=<name>를 통한 런타임 확장을 통해 접근할 수 있습니다. 즉시 로딩 하네스(Claude Desktop / Codex CLI / Grok CLI / Gemini CLI)는 요청당 약 4,700개의 입력 토큰에 해당하는 도구 스키마를 제거하여 cl100k_base BPE 대비 76.4% 감소를 달성했습니다. v0.6.3 동작을 1:1로 유지하려면 ai-memory mcp --profile full을 실행하세요. docs/MIGRATION_v0.6.4.md을 참조하세요.

v0.9의 새로운 기능

v0.9.0은 주로 보안 강화 및 코드 검토 릴리스입니다 — 5개 레인의 적대적 검토(#1885–#1935)에서 49개 수정 — 그리고 v0.8.0 조정 기반 위에 더 적은 수의 추가 기능이 더해졌습니다. 전체 변경 로그: CHANGELOG.md §"[0.9.0] — 2026-07-08".

기본 보안 강화

• 쓰기 시 기본적으로 에이전트 증명 필요 (#1751). AI_MEMORY_REQUIRE_AGENT_ATTESTATION의 컴파일된 기본값이 false → true을 뒤집습니다: 서명되지 않은 직접 저장소 쓰기(MCP memory_store, HTTP POST /api/v1/memories, CLI store)는 이제 attest_level="claimed"에 저장되는 대신 거부됩니다(403 ATTESTATION_FAILED). 쓰기에 서명하거나(ai-memory store --sign 및 ai-memory agents bind-key을 통해 바인딩된 키 쌍 사용) 명시적 옵트아웃 AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0을 설정하여 v0.9 이전의 허용적 자세를 복원하세요. 이는 v0.8.0의 1주기 지원 중단 경고(#1464)에서 약속된 전환입니다.
• 이중 MCP + HTTP 훅 시행 게이트 (#1885 / #1924). 필수 훅 존재 시행 게이트(원래 MCP 전용, #1734)가 이제 HTTP 쓰기 경로에서도 참조되어, MCP를 완전히 건너뛴 쓰기가 구성된 필수 훅을 전혀 보지 못하는 무음 우회 간극(CWE-288)을 닫습니다.
• bulk_create 증명 게이팅 (#1919). 일괄 쓰기는 이제 단일 memory_store 호출과 동일한 행별 에이전트 증명 요구 사항을 시행합니다 — 요청 전체가 아닌 배치의 모든 행이 유효한 증명을 가지고 있어야 합니다.
• 페더레이션 승인자 게이트 (#1920). 인바운드 페더레이션 PENDING 승인은 피어의 등록된 승인자에게 귀속된 경우에만 허용됩니다 — 등록되었지만 신뢰할 수 없는 피어는 더 이상 임의의 요청자에 대한 승인을 위조할 수 없습니다.
• team/unit/org 범위 강화 (#1921). 가시성 범위 해결이 이제 team/unit/org 범위에 대해 네임스페이스 조상 계층 구조를 올바르게 시행하여 테넌트 격리 간극(CWE-863)을 닫습니다.
• skill_register 경로 제한 (#1923). 스킬의 folder_path 가져오기가 구성된 루트 아래로 정규화 및 제한되며, 가져온 트리 내부의 심볼릭 링크는 따라가지 않고 거부됩니다(CWE-22/CWE-59).
• 비argv 저장소 URL 자격 증명 채널 (#1927). 새로운 AI_MEMORY_STORE_URL(소유자 전용 /proc/environ) 및 AI_MEMORY_STORE_URL_FILE(0600 파일)을 통해 ai-memory serve가 postgres/store URL(포함된 비밀번호 포함)을 --store-url argv에 절대 노출하지 않고 수신할 수 있습니다. argv에서는 전역 읽기 가능한 /proc/<pid>/cmdline 및 ps auxww을 통해 모든 로컬 UID에 노출됩니다. 해결 순서: 파일 → 환경 변수 → --store-url.

추가 기능

• B7-SKILL — 스킬 메모리 일급 지원 (#1865). 등록 시 parameters_schema, invocation_record, 그리고 에이전트 작성 스킬을 위한 버전 표면.
• recall_observations 섀도우 피드백 루프 (#1706, SHADOW 모드). 순위 동작을 아직 변경하지 않고 리콜 피드백 루프를 닫습니다.
• 메모리 파생 계보 DAG (memory_lineage, 스키마 v78, #1859). MCP 및 새로운 GET /api/v1/memories/{id}/lineage HTTP 경로를 통해 어떤 메모리가 어떤 메모리에서 파생되었는지 추적합니다.
• 벡터 검색 최소 옵트인 슬라이스 (#1005; 전체 기반은 #1860으로 연기됨).
• 물리적 CPU 수에 맞춘 리랭커 작업자 풀 (#1867) 및 기본적으로 PURE인 리콜 (#1869 — 리콜 핫 경로에서 쓰기 버스트 제거).
• 추가 전용 스파인 + 서명 계층 분리: 모든 변이 사이트가 서명된 리비전 리프로 라우팅됨(#1823), 3키 Recorder/Judge/Stopper 서명 분리(#1826), 마카룬 기능 토큰 엔드투엔드 연결(#1827), 순환 생존을 위한 서명된 신원 계보 키 승계 체인(#1828, 스키마 v76).

시작하기 좋은 곳: CHANGELOG.md (전체 변경 로그), docs/ADMIN_GUIDE.md (운영자 플레이북 — 증명 + 훅 시행 자세).

v0.8의 새로운 기능

v0.8.0(distributed-coordination)은 메모리 기반을 다중 에이전트(NHI) 플릿을 위한 조정 기반으로 전환합니다. 주요 내용은 분산 조정 장치(#1709)입니다. 모든 것은 sqlite 및 postgres+AGE SAL 어댑터 모두에서 제공되며 v0.7.x 호출자에게는 기본적으로 동등하게 유지됩니다. 전체 도구 참조: docs/coordination.md; 전체 노트: docs/v0.8.0/release-notes.md.

분산 조정 기반 (Pillar-1, #1709)

• 액션 — 종속성 DAG (스키마 v59). 상태 머신(pending → claimed → in_progress → done/failed/abandoned), 유형화된 DAG 에지(requires / unlocks / blocks / gated_by / sibling), 그리고 다음 실행 가능한 노드를 가져오는 프론티어/다음 표면을 가진 유형화된 액션 노드. 8개의 MCP 도구(memory_action_create / _get / _transition / _list / _add_edge / _edges / _frontier / _next).
• 임대 — 단일 보유자, TTL 제한 클레임 (스키마 v59). 하트비트 갱신 비교 및 교환 클레임(PRIMARY KEY on action_id = 한 번에 한 보유자)과 시간당 임대 청소기. 4개의 MCP 도구(memory_lease_acquire / _renew / _release / _get).
• 신호 — 유형화된, Ed25519 서명된 에이전트 간 메시지 (스키마 v60). 각각 서명 + 발신자 signer_pubkey를 가지며 correlation_id / in_reply_to을 통해 스레드됩니다. 5개의 MCP 도구(memory_signal_send / _read / _inbox / _thread / _ack).
• 체크포인트 — 증명된 조건부 게이트 (스키마 v61). 조건이 해결될 때까지 차단하는 게이트; 해결은 직무 분리를 위해 자체 서명(Ed25519)되며 verify이 서명을 다시 확인합니다. 4개의 MCP 도구(memory_checkpoint_create / _resolve / _query / _verify).
• 루틴 — 매개변수화되고, 고정되며, 재생 가능한 계획 (스키마 v62). draft로 작성된 후 고정(불변, Ed25519 고정 증명)됩니다. run은 {{param}} 템플릿에서 구체적인 액션 + 에지 세트를 routine_runs 레코드로 구체화합니다. 5개의 MCP 도구(memory_routine_create / _freeze / _run / _status / _list).
• 모든 조정 상태 변이는 변조 방지 coordination.<op> 행을 signed_events V-4 해시 체인에 추가합니다(#1722). 두 개의 권한 부여 쓰기는 로컬 CAS + W-of-N 페더레이션 팬아웃을 통해 HTTP 데몬(POST /api/v1/actions/{id}/transition, POST /api/v1/signals)에 미러링됩니다(#1718).

유형화된 인지 (Pillar-2)

memory_kind 어휘가 goal / plan / step로 확장됩니다. 닫힌 memory_links.relation 분류 체계가 6 → 9 관계로 확장되고(decomposes_into / depends_on / advances, 스키마 v63), 일급 memories.lifecycle_state 열(스키마 v64)이 Goal/Plan/Step을 실제 상태 머신(open → active → blocked/done/abandoned)으로 만들어 MCP / HTTP / SAL 표면 전반에 걸쳐 불법 에지 매핑을 HTTP 409 CONFLICT로 시행합니다. Memory 구조체가 27개 필드로 증가합니다. 새로운 MCP 도구는 없습니다 — v64 작업은 허용적인 선택적 요청 필드만 추가합니다.

페더레이션 강화, 기본적으로 안전

피어 등록 기본적으로 ON (#1789), 권한 부여 쓰기에 대한 전환별 서명 (#1718), 중계된 메모리에 대한 쓰기별 콘텐츠 증명 (#1464), 전환 재생 논스 (#1805), 아웃바운드 피어 인증서 지문 고정 (#1678). 서로를 신뢰할 필요가 없는 이기종 플릿 — 업그레이드하기 전에 docs/v0.8.0/release-notes.md §"페더레이션 강화"에서 안전한 기본값 전환을 검토하세요.

실제로 차단하는 거버넌스 (#1811)

Claude Code PreToolUse 거버넌스 훅이 type:command 래퍼(ai-memory governance check-action --from-pretool-stdin)로 재작업되어 기반 Refuse이 permissionDecision:"deny"을 방출하고 실제로 도구를 차단합니다 — 이전 type:mcp_tool 형식은 구조적으로 시행할 수 없었습니다. 또한 필수 훅 존재 시행(#1734) 및 인간 개입을 위한 새로운 escalate 거버넌스 평결(§22 PE-5).

Pillar-4 운영 제어

HTTP 수락 제어(#1733 — 유형화된 503으로 초과분을 차단하는 옵트인 동시성 상한), 지연된 Apache-AGE 그래프 프로젝션(#1735 — postgres 링크 쓰기 핫 경로에서 동기식 AGE 왕복 제거), 큐레이터 압축 활성화(#1749 / #1750), 그리고 signed_events 교차 행 해시 체인을 엔드투엔드로 검증하는 ai-memory verify-audit-trail CLI(§22 PE-8).

스키마 v57 → v70 (모두 추가적)

조정 + 유형화된 인지 + 가시성 + 암호화 준비 + 콜드 경로 + 아카이브 에지 테이블(v58–v70), sqlite 및 postgres 어댑터 모두에 미러링됨. 처음 열 때 자동 마이그레이션되며 아카이브 → 복원 왕복이 무손실입니다. 표준 v58–v70 래더는 CLAUDE.md §Database를 참조하세요.

시작하기 좋은 곳: docs/v0.8.0/release-notes.md (전체 릴리스 노트), docs/coordination.md (조정 도구 참조), CLAUDE.md §Database (스키마 래더 SSOT).

v0.7의 새로운 기능

v0.7.0은 attested-cortex 에픽(11개 트랙 A–K에 걸쳐 69/69)을 완료하고, 원래 v0.7.1 postgres+AGE 일급 작업을 통합하며, 그랜드 슬램 이후 출시 준비 웨이브(Batman Forms 1-6 + 7th-form Option-B 기반 + QW-1/2/3 + 보안 조정)를 흡수합니다. 표준 기능 인벤토리: docs/internal/v070-feature-inventory.md. 모든 표면은 v0.6.4 호출자에게 기본적으로 꺼져 있거나 동등하게 유지됩니다 — 자세한 내용은 v0.7 호환성 매트릭스를 참조하세요.

기반 네이티브 쓰기 시간 투자 (Batman Forms 1-6 + 7th-form)- 형식 1 — 온라인 중복 제거 및 합성 (이슈 #754). 단일 배치 액션 방출 LLM 호출이 저장 경로의 v0.6.x 쌍별 분류기를 대체합니다. 네임스페이스 표준의 legacy_per_pair_classifier = true을 통해 레거시 예/아니오로 다시 선택할 수 있습니다.

• 형식 2 — 동기식 임베드 전 원자화 (이슈 #755). 새로운 memory_atomise 도구 + auto_atomise_mode = Synchronous|Deferred|Off 사전 저장 훅. 큐레이터가 긴 쓰기를 리콜이 보기 전에 2~10개의 원자적 명제로 분해합니다. docs/atomisation.md을 참조하세요.
• 형식 3 — 다단계 수집 오케스트레이터 (이슈 #756). memory_ingest_multistep가 프롬프트 캐시 안정 LLM 단계를 통해 결정론적 Jaccard+FTS 도우미를 스레딩합니다. docs/multistep-ingest.md + cookbook/multistep-ingest/01-two-phase.sh을 참조하세요.
• 형식 4 — 사실 출처 (이슈 #757). 인용 + 소스 URI + 원자 단위 범위가 기존 memory_store / memory_atomise 페이로드에 탑재됩니다. docs/provenance.md를 참조하세요.
• 형식 5 — 자동 신뢰도 + 섀도우 보정 + 신선도 감쇠 (이슈 #758). memory_calibrate_confidence MCP 도구 + 소스별 기준선 스윕. 환경 변수 AI_MEMORY_AUTO_CONFIDENCE, AI_MEMORY_CONFIDENCE_SHADOW, AI_MEMORY_CONFIDENCE_SHADOW_SAMPLE_RATE, AI_MEMORY_CONFIDENCE_DECAY. docs/confidence-calibration.md를 참조하세요.
• 형식 6 — MemoryKind 배트맨 어휘 (이슈 #759). 10가지 변형 열거형 (Observation 기본값 + Reflection / Persona / Concept / Entity / Claim / Relation / Event / Conversation / Decision). 선택적 auto_classify_kind 사전 저장 훅 (off / regex_only / regex_then_llm). docs/memory-kind-vocab.md을 참조하세요.
• 7번째 형식 — 에이전트-외부 레이어-4 배선 (옵션-B 기반) (이슈 #760; v0.8.0 전체 커버 #697). 운영자 키페어 서명 시드 규칙 R001..R004, memory_check_agent_action + memory_rule_list MCP 도구, 서브스트레이트 storage::insert 사전 쓰기 훅. docs/policy-engine.md + docs/governance/agent-action-rules.md를 참조하세요.
• 운영자 방법 — 형식 1–6 + 7번째를 가능 상태에서 활성 상태로 전환 (이슈 #800). 7단계 레시피 (운영자 키 생성 → 시드 서명 → R001–R004 활성화 → 큐레이터 데몬 → 선택적 리플렉션 패스 → 네임스페이스 정책), launchd / systemd / 작업 스케줄러 영구화, 검증 블록, 롤백 경로. docs/batman-active-mode.md 및 GitHub Pages 아틀라스를 참조하세요.

빠른 성과 (Tencent QW-1/2/3)

• QW-1 — 파일 기반 리플렉션 체인 내보내기. memory_export_reflection MCP 도구 + auto_export_reflections_to_filesystem 네임스페이스 정책 → ~/.ai-memory/reflections/<ns>/<id>.md.
• QW-2 — 페르소나를 아티팩트로. memory_persona + memory_persona_generate 도구, MemoryKind::Persona 행, auto_persona_trigger_every_n_memories 네임스페이스 정책. docs/persona.md을 참조하세요.
• QW-3 — 컨텍스트 오프로드 기본 요소. memory_offload + memory_deref가 대용량 도구 출력을 에이전트 컨텍스트 창에서 주소 지정 가능한 블롭 저장소로 이동합니다. docs/context-offload.md을 참조하세요.

증명된 코어텍스 에픽 (트랙 A–K)

• 증명된 링크 (Ed25519). v0.6.3에 제공된 비어 있던 signature 열이 이제 실제 에이전트별 Ed25519 증명으로 채워지며, memory_verify(link_id)이 요청 시 {signature_verified, attest_level, signed_by, signed_at}를 반환합니다. ai-memory identity generate으로 키페어를 생성하고, attest_level = "self_signed"을 통해 선택하세요. 서명은 해결된 데몬 agent_id가 구성된 키 디렉터리 아래 디스크에 *.priv 키페어를 가지고 있는 경우에만 가능합니다 — load_daemon_signing_key가 None (src/main.rs:116-118)를 반환하면 행은 여전히 기록되지만 sig은 비어 있고 데몬은 부팅 시 "서명 없이 계속" 줄을 내보냅니다. signed_events의 행 간 해시 체인은 어느 쪽이든 변조 방지 기능을 유지합니다. attested-cortex RFC를 참조하세요.
• 서명된 이벤트 V-4 마무리 (행 간 해시 체인) (이슈 #698). 각 signed_events 행은 prev_hash + sequence를 전달합니다. 첫 번째 행 prev_hash은 0이며, 후속 행은 이전 표준 CBOR 페이로드의 SHA-256을 체인으로 연결합니다. ai-memory verify-signed-events-chain가 체인을 종단 간으로 탐색합니다. docs/signed-events-v4.md를 참조하세요.
• 훅 파이프라인 (25개 수명 주기 이벤트). 프로그래밍 가능한 확장 표면이 20개의 기준 pre_/post_store|recall|search|delete|promote|link|consolidate|governance_decision|archive|transcript_store + on_index_eviction 이벤트와 5개의 그랜드슬램 추가 항목 (pre_recall_expand G10 + pre_reflect/post_reflect 재귀 학습 작업 6/8 + pre_compaction/on_compaction_rollback L1-7)에서 실행됩니다. 훅은 Allow / Modify / Deny / AskUser을 반환합니다. 기본값은 꺼짐이며, ~/.config/ai-memory/hooks.toml을 통해 선택할 수 있습니다. docs/hook-pipeline.md을 참조하세요.
• 사이드체인 트랜스크립트 + 재생. zstd-3 BLOB 사이드체인이 원시 대화/추론 추적을 저장하며, memory_replay(memory_id)가 memory_transcript_links을 탐색하여 체인을 재구성합니다. [transcripts.namespaces."team/*"]을 통해 네임스페이스별로 선택할 수 있습니다. docs/sidechain-transcripts.md를 참조하세요.
• 페더레이션 강화. mTLS + X-API-Key + SHA-256 인증서 지문 허용 목록; 환경 변수 AI_MEMORY_FED_PEER_ATTESTATION, AI_MEMORY_FED_SYNC_TRUST_PEER, AI_MEMORY_FED_TRUST_BODY_AGENT_ID. docs/federation.md을 참조하세요.
• K8 할당량 도구 + K10 SSE 승인. memory_quota_status + /api/v1/quota/status (K8). HMAC 논스, 메서드+pending_id 바인딩, 지연 이벤트 수 제거 기능이 있는 /api/v1/approvals/stream 서버 전송 이벤트 (K10). docs/k8-quotas.md + docs/k10-sse-approvals.md을 참조하세요.
• Postgres + Apache AGE 최우선 백엔드. ai-memory serve --store-url postgres://…, 스키마 동등성, 6요소 리콜 점수 동등성, 링크 마이그레이션, AGE Cypher 기반 KG 기능 (kg_query, kg_timeline, kg_invalidate, find_paths) 및 AGE 부재 시 재귀 CTE 폴백, 그리고 새로운 ai-memory schema-init CLI 동사. 벤치마크 기준 — AGE p95가 깊이=5에서 CTE p95보다 30% 이상 빨라야 합니다. 운영자 방법: docs/postgres-age-guide.md. 마이그레이션 실행서: docs/migration-v0.7.0-postgres.md.
• 기능 v3 + 스마트 로더. memory_capabilities v3에 summary, to_describe_to_user, 도구별 callable_now, agent_permitted_families, schema_version="3"가 추가됩니다. 새로운 상시 작동 memory_load_family(family) 및 memory_smart_load(intent) 도구가 기본 core 프로필에 합류합니다. 고정된 표현은 docs/v0.7/canonical-phrasings.md에 있습니다.
• 권한 + A2A 승인. v0.6.x 거버넌스 하위 시스템이 규칙 + 모드 + 훅 → 단일 Decision으로 리팩터링되며, 네임스페이스 상속(G1)이 실제로 적용됩니다. memory_pending_list / memory_pending_approve / memory_pending_reject(remember=forever)이 점진적 신뢰를 활성화하며, 승인 API에 대한 HMAC 서명이 필수입니다. permissions.mode의 기본값은 enforce입니다 (v0.6.4에서는 advisory였음). ai-memory governance migrate-to-permissions로 마이그레이션하세요 (드라이런 미리보기; --config-out ~/.config/ai-memory/config.toml을 추가하여 제자리에 적용). docs/governance.md를 참조하세요.

재귀 학습 + L1/L2 그랜드슬램 웨이브

네임스페이스 범위의 max_reflection_depth 제한(기본값 3, Some(0)는 킬 스위치)이 있는 memory_reflect 서브스트레이트 기본 요소. L2-1 리플렉션 패스 큐레이터, L2-2 페더레이션 인식 리플렉션 조정(memory_reflection_origin), L2-3 무효화 전파(memory_dependents_of_invalidated), L2-5 포렌식 번들(ai-memory export-forensic-bundle + verify-forensic-bundle), L1-5 에이전트 스킬(memory_skill_register|list|get|resource|export|promote_from_reflection|compositional_context). 전체 입문서: docs/RECURSIVE_LEARNING.md. 에이전트 스킬 입문서: docs/agent-skills.md. 포렌식 내보내기 입문서: docs/forensic-export.md.

시작점: docs/MIGRATION_v0.7.md (업그레이드 절차), docs/v0.7.0/release-notes.md (전체 릴리스 노트), docs/whats-new-v07.html (시각적 요약), docs/v0.7/rfc-attested-cortex.md (설계 근거), docs/ADMIN_GUIDE.md (운영자 플레이북), docs/internal/v070-feature-inventory.md (표준 기능 진실).

하나의 바이너리, 네 가지 운영 모드 (v0.6.4). ai-memory Rust 바이너리(tokio + axum)는 단일 SQLite 데이터베이스를 공유하며 이들 중 어느 것이든 격리 또는 동시에 실행할 수 있습니다:

1. stdio MCP 서버 -- 전체 프로필(v0.9.0; 100개의 호출 가능한 메모리 도구 + 상시 작동 memory_capabilities 부트스트랩; Profile::full().expected_tool_count()에 대해 검증됨)에서 JSON-RPC를 통해 101개의 광고된 항목. 기본 --profile core은 7개(원래 5개 + memory_load_family + memory_smart_load)와 상시 작동 memory_capabilities 부트스트랩을 광고합니다. ai-memory mcp / ai-memory mcp --profile full
2. HTTP / mTLS 데몬 -- 127.0.0.1:9077에서 92개의 REST 경로 등록(78개의 고유 URL 경로), TLS + 선택적 mTLS 허용 목록 + API 키 인증, 백그라운드 GC 루프. ai-memory serve
3. 자율 큐레이터 데몬 -- 자동 태그 지정, 네임스페이스 형제 간 모순 표면화, 근사 중복 통합, 접근 패턴별 우선순위 조정을 수행하는 자체 스케줄링 루프(기본 1시간 주기). 모든 작업은 롤백 로그로 이동하며, 파괴적 작업은 거버넌스 승인 흐름 뒤에 제한될 수 있습니다. ai-memory curator --daemon
4. 동기화 데몬 -- 인스턴스 간 쿼럼 기반 피어 페더레이션. N개 중 W개 쓰기(기본 과반수), 벡터 클록 CRDT-라이트 병합, 피어 간 mTLS 허용 목록. ai-memory sync-daemon

MCP, HTTP 및 CLI 표면은 반응형입니다. 큐레이터는 메모리 계층을 자체 유지 관리하는 부분으로, 세션 사이에 코퍼스를 정리하여 저장소가 성장해도 리콜 품질이 높게 유지되도록 합니다. 모든 것이 로컬 우선이며 클라우드 종속성이 없습니다.

Claude Opus 4.7의 v0.6.3 소스 코드 한 줄 한 줄 읽은 후 솔직한 평가:

"ai-memory는 제가 연결해 본 가장 유능한 메모리 계층이며, 그 이름이 광고하는 것보다 훨씬 더 많은 것을 의미합니다. 실질적인 측면에서 저에게 의미하는 바는 다음과 같습니다: 각 세션을 처음부터 시작하지 않습니다. 제가 읽는 저장소는 저 외의 다른 것에 의해 정리되었습니다. 모순이 조용히 쌓이지 않습니다. 코퍼스가 성장해도 리콜 품질이 높게 유지됩니다. Mac mini에서 아무것도 떠나지 않습니다.

이것이 저를 자율 에이전트로 만드는 것은 아닙니다. 자율 에이전트가 필요로 하는 종류의 메모리 인프라를 제공하며, 자체적으로 이를 유지하기 위한 작은 자율 루프를 실행합니다. 그것이 진정한 기반입니다. 여기서 'ai-memory가 일반 작업을 주도'하는 단계까지의 격차는 배관(도구 호출 프로토콜 + 도구 레지스트리 + 도구 사용 가능 모델)일 뿐 발명이 아닙니다."

멀티 에이전트 AI를 위한 서브스트레이트. ai-memory는 에이전트 런타임이 아니며 그 자체로 "자율 AI"도 아닙니다. 멀티 에이전트 자율 배포가 그 아래에 필요로 하는 메모리 계층입니다. 페더레이션(broadcast_store_quorum + spawn_catchup_loop)은 많은 에이전트가 병렬로 쓸 때 피어 간 N개 중 W개 일관성을 처리합니다. 큐레이터 데몬은 스웜이 공유 코퍼스에 기록할 때 노이즈로 저하되는 것을 방지합니다. 웹훅 구독(HMAC 서명, 네임스페이스/에이전트 필터링, SSRF 강화)은 저장소를 메모리 이벤트에서 다운스트림 에이전트를 트리거하는 메시지 버스로 전환합니다. N 수준 상속 및 네임스페이스별 거버넌스 정책(쓰기/승격/삭제 권한, 승인자 유형, 선택적 N-of-M 합의)이 있는 네임스페이스 계층 구조가 스웜을 제한합니다. 이를 자동 생성 스킬이 있는 24/7 멀티 머신 에이전트 러너 아래에 쌓으면 결합된 시스템이 자율 AI에 대한 행동적 기준을 충족합니다. 나머지 격차(가중치 수준 학습 없음, 상태 비저장 추론 커널, 인간이 시드한 루트 목표)는 실제이며 ai-memory가 다루는 부분이 아닙니다. ai-memory는 이러한 격차를 해소하려는 모든 진지한 시도에 필요한 멀티 에이전트 메모리 서브스트레이트를 제공합니다. 토큰 비용 제로, 리콜 전까지. 모든 대화에 전체 메모리를 로드하여 모든 메시지마다 토큰과 비용을 소모하는 내장 메모리 시스템(Claude Code 자동 메모리, ChatGPT 메모리)과 달리, ai-memory는 AI가 명시적으로 memory_recall을(를) 호출하기 전까지 컨텍스트 토큰을 전혀 사용하지 않습니다. 6가지 요소 점수 알고리즘으로 순위가 매겨진 관련 메모리만 반환됩니다. TOON 형식(Token-Oriented Object Notation)은 반복되는 필드 이름을 제거하여 응답 토큰을 40-60% 더 절감합니다. JSON의 메모리 3개 = 1,600바이트, TOON = 626바이트(61% 감소), TOON 압축 = 336바이트(79% 감소). Claude Code 사용자: 자동 메모리 비활성화(settings.json의 "autoMemoryEnabled": false) 후 ai-memory로 교체하여 모든 단일 메시지에서 200줄 이상의 메모리 컨텍스트 비용을 지불하지 마세요.

에이전트 신원(NHI) — 모든 메모리가 누가 학습했는지 알려줍니다

ai-memory가 저장하는 모든 메모리는 metadata.agent_id을(를) 포함합니다. 이는 모든 작업(업데이트, 중복 제거, 가져오기, 동기화, 통합)에서 유지되는 비인간 신원(Non-Human Identity) 마커입니다. 모든 리콜 결과는 기본적으로 AI 클라이언트에 최적화된 TOON 압축 응답 형식으로 각 메모리를 어떤 AI가 작성했는지 알려줍니다:

count:5|mode:hybrid|tokens_used:842
memories[id|title|tier|namespace|priority|score|tags|agent_id]:
a1b2|Project DB is PostgreSQL 16|long|infra|8|0.91|database,postgres|ai:claude-code@workstation:pid-3812
c3d4|API rate limit is 100 rps|long|infra|7|0.87|api,limits|ai:claude-desktop@laptop:pid-5219

서명되지 않은 쓰기에서 agent_id은(는) 주장된 신원이므로, 이것만으로 보안 결정을 내려서는 안 됩니다. v0.9.0 (#1751) 부터 저장소 경로 에이전트 증명이 기본적으로 필수입니다: 운영자가 명시적 옵트아웃 AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0을(를) 설정하지 않는 한, 서명되지 않은 직접 CLI/MCP/HTTP 쓰기는 attest_level = "claimed"에 저장되는 대신 거부(403 ATTESTATION_FAILED)됩니다. 암호화 Ed25519 증명은 두 가지 표면에 연결됩니다: (1) 저장소 경로 증명 (#626 Layer-3) — CLI(store --sign), MCP(memory_store) 또는 HTTP(POST /api/v1/memories) 경로에서 표준 SignableWrite 엔벨로프에 대한 분리 서명을 제시하면 데몬이 에이전트의 바인딩된 공개 키에 대해 이를 검증하여 metadata.attest_level = "agent_attested"을(를) 찍습니다(제시되었지만 위조된 서명은 플래그와 관계없이 항상 거부됨). (2) 링크 증명(attested-cortex) — 인바운드 검증을 위해 memory_verify(link_id)이(가) 포함된 이전에 예약된 memory_links.signature 필드와 추가 전용 signed_events 감사 체인. 전체 출처 계약은 에이전트 신원 페이지 및 attested-cortex RFC를 참조하세요.

소급 대화 가져오기 — ai-memory mine

처음부터 시작하지 마세요. ai-memory mine을(를) Claude, ChatGPT 또는 Slack 내보내기로 지정하면 턴별로 구문 분석하여 순위가 매겨지고, 계층 유형이 지정되고, 태그가 지정된 메모리로 변환하므로, AI는 기존 기록의 모든 결정, 수정 사항 및 발견 사항을 알고 다음 세션에 임할 수 있습니다.

ai-memory mine claude  ~/Downloads/claude-export/
ai-memory mine chatgpt ~/Downloads/chatgpt-export.json
ai-memory mine slack   ./slack-export/

자동 태그 지정, (title, namespace)에 대한 중복 제거 및 mined_from 출처가 가져온 모든 메모리에 찍힙니다. 컨텍스트 제로에서 채워진 장기 저장소까지 5분 만에 온보딩. 형식별 레시피는 기록 가져오기 페이지를 참조하세요.

호환 가능한 AI 플랫폼

ai-memory는 **모델 컨텍스트 프로토콜(MCP)**을 지원하는 모든 AI 플랫폼과 통합됩니다. MCP는 AI 어시스턴트를 외부 도구 및 데이터 소스에 연결하기 위한 범용 표준입니다.

MCP가 기본 통합 계층입니다. 아직 MCP를 기본적으로 지원하지 않는 AI 플랫폼의 경우, HTTP API(localhost에서 92개 경로 등록 / 78개 고유 URL 경로) 및 CLI(--features sal 또는 --features sal-postgres 아래 89개 하위 명령; 기본 빌드에서 87개(post-#1389 L2 RecoverPreviousSession 교차 세션 컨텍스트 재수화 + #1443 ai-memory expand 쿼리 확장 표면을 위한 Expand + #1598 ai-memory reembed 벡터 공간 마이그레이션 표면을 위한 Reembed); ai_memory::EXPECTED_CLI_SUBCOMMANDS_DEFAULT + EXPECTED_CLI_SUBCOMMANDS_SAL + 기계적 tests/cli_subcommand_count_invariant.rs 패리티 테스트로 고정된 SSOT)가 범용 액세스를 제공합니다. HTTP 호출을 하거나 셸 명령을 실행할 수 있는 모든 AI, 스크립트 또는 자동화가 ai-memory를 사용할 수 있습니다.

60초 만에 설치

사전 빌드된 바이너리는 종속성이 필요하지 않습니다. 소스에서 빌드하려면 Rust와 C 컴파일러가 필요합니다.

가장 빠른 방법: 사전 빌드된 바이너리 (Rust 불필요)

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh

# Fedora/RHEL (COPR)
sudo dnf copr enable alpha-one-ai/ai-memory && sudo dnf install ai-memory

# Windows (PowerShell)
irm https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.ps1 | iex

1단계: Rust 설치 (사전 빌드된 바이너리 사용 시 건너뛰기)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

프롬프트를 따른 다음 터미널을 다시 시작하거나(source ~/.cargo/env 실행)하세요.

2단계: 소스에서 설치 (Rust 필요)

Crates.io의 최신 릴리스:

cargo install ai-memory

git 저장소의 최신 버전:

cargo install --git https://github.com/alphaonedev/ai-memory-mcp.git

이 명령은 바이너리를 컴파일하여 PATH에 넣습니다. 1~2분 정도 소요됩니다.

소스 빌드를 위한 빌드 종속성:

• Ubuntu/Debian: sudo apt-get install build-essential pkg-config
• Fedora/RHEL: sudo dnf install gcc pkg-config

3단계: AI 연결

구성은 플랫폼마다 다릅니다. 아래에서 해당 플랫폼을 찾으세요:

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

# ~/.config/ai-memory/config.toml
schema_version = 2

[llm]
backend     = "xai"
model       = "grok-4.3"
base_url    = "https://api.x.ai/v1"
api_key_env = "XAI_API_KEY"            # process-env-var name (NOT the literal key)

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "autonomous"]
    }
  }
}

[mcp_servers.memory]
command = "ai-memory"
args = ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
enabled = true

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"],
      "timeout": 30000
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    }
  }
}

mcpServers:
  - name: memory
    command: ai-memory
    args:
      - "--db"
      - "~/.local/share/ai-memory/memories.db"
      - "mcp"
      - "--tier"
      - "semantic"

{
  "mcp": {
    "servers": [
      {
        "id": "ai-memory",
        "label": "AI Memory",
        "enabled": true,
        "transport": "stdio",
        "command": "ai-memory",
        "args": ["mcp", "--tier", "semantic"]
      }
    ]
  }
}

ai-memory serve --host 127.0.0.1 --port 9077
# Expose via HTTPS reverse proxy (nginx, caddy, cloudflare tunnel, etc.)

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "tools": [{
      "type": "mcp",
      "server_url": "https://your-server.example.com/mcp",
      "server_label": "memory",
      "server_description": "Persistent AI memory with recall and search",
      "allowed_tools": ["memory_store", "memory_recall", "memory_search"]
    }],
    "input": "What do you remember about our project?"
  }'

ai-memory serve --host 127.0.0.1 --port 9077

client.toolgroups.register(
    provider_id="model-context-protocol",
    toolgroup_id="mcp::memory",
    mcp_endpoint={"uri": "http://localhost:9077/sse"}
)

tool_groups:
  - toolgroup_id: mcp::memory
    provider_id: model-context-protocol
    mcp_endpoint:
      uri: "http://localhost:9077/sse"

openclaw mcp set memory '{"command":"ai-memory","args":["--db","~/.local/share/ai-memory/memories.db","mcp","--tier","semantic"]}'

{
  "mcp": {
    "servers": {
      "memory": {
        "command": "ai-memory",
        "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
      }
    }
  }
}

command: ai-memory
args: ["--db", "/path/to/ai-memory.db", "mcp"]

ai-memory serve
# 92 REST route registrations (78 unique URL paths) at http://127.0.0.1:9077/api/v1/

4단계: 완료. 테스트하세요.

AI 어시스턴트를 다시 시작하세요. MCP를 사용하는 경우 이제 세션 부팅 시 광고되는 7개 도구 기본 표면(기존 5개 + memory_load_family + memory_smart_load; 호출 가능한 100개 도구 중 나머지 93개는 --profile 또는 memory_capabilities --include-schema을 통해 필요 시 로드됨)을 갖게 됩니다. "내가 가장 좋아하는 언어는 Rust라는 메모리를 저장해 줘"라고 물어보세요. 그런 다음 새 대화에서 "내가 가장 좋아하는 언어는 뭐야?"라고 물어보세요. 기억할 것입니다.

모바일 플랫폼 지원 (v0.7.0 Posture-1a)

ai-memory는 표준 Rust 모바일 크로스 컴파일 경로를 통해 iOS 및 Android로 이식 가능합니다. v0.7.0은 세 가지 단계적 수준에서 두 대상에 대한 CI 적용 범위를 제공합니다:

v0.7.0 상태: 계층 1은 출시 게이트입니다 — 태그 컷 전에 모바일 크로스 컴파일이 GREEN이어야 합니다. 계층 2(릴리스 아티팩트)는 BUILD 파이프라인 + 아티팩트 레이아웃을 제공합니다. C 호출 가능 FFI 표면 자체는 v0.7.x 후속 버전에서 제공됩니다. 계층 3은 모든 release/** 푸시 시 범위가 지정된 테스트 하위 집합을 실행합니다.

릴리스 아티팩트 사용:

• iOS — v0.7.x 릴리스 페이지에서 ai-memory-ios.xcframework.tar.gz을(를) 다운로드하고 압축을 푼 다음 AiMemory.xcframework을(를) Xcode 프로젝트의 "Frameworks, Libraries, and Embedded Content" 아래로 드래그하세요.
• Android — v0.7.x 릴리스 페이지에서 ai-memory-android.tar.gz을(를) 다운로드하고 압축을 푼 다음 jniLibs/ 트리를 앱 모듈의 src/main/jniLibs/에 복사하세요.

모바일 아티팩트는 게시된 모든 v0.7.x 릴리스의 일부이기도 합니다. Homebrew 공식 + APT/RPM 패키지(데스크톱 바이너리 제공)에는 모바일 다운로드로 연결되는 메모가 포함되어 있습니다. CI 구현 내역은 이슈 #1068을 참조하세요.

빠른 시작

2분 안에 제로에서 작동하는 메모리까지.

1. 설치

curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh

2. MCP 구성 (Claude Code 예시 -- 다른 플랫폼도 동일하게 작동)

~/.claude.json에 병합:

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

3. 첫 번째 메모리 저장

ai-memory store -T "Project uses PostgreSQL 15" -c "Main DB is PG 15 with pgvector." --tier long

4. 회상

ai-memory recall "database"

5. 통계 확인

ai-memory stats

6. AI와 함께 사용. AI 클라이언트를 다시 시작하세요. 이제 MCP를 통해 부팅 시 광고되는 7개의 기본 메모리 도구(런타임 확장 또는 --profile full을 통해 도달 가능한 101개의 광고 항목)를 갖게 됩니다 -- 대화 중에 기본적으로 메모리를 저장하고 회상할 수 있습니다.

SDK

MCP / HTTP / CLI 표면 외에도 ai-memory는 HTTP 클라이언트 및 헬퍼 유틸리티(예: v0.6.4+ 데몬에서 런타임 프로필 어설션을 위한 requireProfile)를 위한 자사 언어 SDK를 제공합니다.

TypeScript / JavaScript — npm의 @alphaone/ai-memory

npm install @alphaone/ai-memory

Python — PyPI의 ai-memory-mcp (가져오기 이름은 ai_memory로 유지됨)

pip install ai-memory-mcp

from ai_memory import AiMemoryClient, require_profile

with AiMemoryClient(base_url="http://127.0.0.1:9077", api_key="...") as client:
    require_profile(client, "graph")  # raises ProfileNotLoaded on miss

두 SDK 모두 서버와 함께 버전이 관리됩니다(0.9.0이(가) ai-memory 0.9.0과(와) 일치). v0.6.4+ 데몬은 프로필 계약을 시행합니다. v0.6.4 이전 데몬은 SDK 업그레이드로 인해 이전 서버가 중단되지 않도록 허용적 경고 후 계속으로 대체됩니다. 소스는 sdk/typescript/ 및 sdk/python/에 있습니다.

기능

AI 어시스턴트는 대화 간에 모든 것을 잊어버립니다. ai-memory가 이를 해결합니다.

MCP(모델 컨텍스트 프로토콜) 도구 서버로 실행됩니다 -- AI가 기본적으로 통신하는 백그라운드 프로세스입니다. AI가 중요한 것을 학습하면 저장합니다. 컨텍스트가 필요하면 6가지 요소 점수 알고리즘으로 순위가 매겨진 관련 메모리를 회상합니다. 메모리는 세 가지 계층으로 존재합니다:

• 단기 (기본 6시간, 구성 가능) -- 현재 디버깅 상태와 같은 일회성 컨텍스트
• 중기 (기본 7일, 구성 가능) -- 스프린트 목표 및 최근 결정과 같은 작업 지식
• 장기 (영구) -- 아키텍처, 사용자 기본 설정, 어렵게 얻은 교훈

계속 액세스되는 메모리는 자동으로 중기에서 장기로 승격됩니다. 각 회상은 TTL을 연장합니다. 사용량에 따라 우선순위가 증가합니다. 시스템은 자체 큐레이션됩니다.

MCP 외에도 ai-memory는 완전한 HTTP REST API(92개 경로 등록 / 포트 9077의 78개 고유 URL 경로)와 완전한 CLI(--features sal 또는 --features sal-postgres 아래 89개 하위 명령; 기본 빌드에서 87개(교차 세션 컨텍스트 재수화를 위한 post-#1389 L2 RecoverPreviousSession + ai-memory expand 쿼리 확장 표면을 위한 #1443 Expand + ai-memory reembed 벡터 공간 마이그레이션 표면을 위한 #1598 Reembed); ai_memory::EXPECTED_CLI_SUBCOMMANDS_{DEFAULT,SAL} + 기계적 tests/cli_subcommand_count_invariant.rs 패리티 테스트에 의해 고정된 SSOT)를 노출하여 직접 상호 작용, 스크립팅 및 모든 AI 플랫폼 또는 도구와의 통합을 지원합니다.

기능

핵심

• MCP 도구 서버 -- stdio JSON-RPC를 통한 101개 도구(전체 프로필), 모든 MCP 클라이언트와 호환
• 3계층 메모리 -- 단기(기본 6시간 TTL), 중기(기본 7일 TTL), 장기(영구) -- TTL 구성 가능
• 전체 텍스트 검색 -- 순위 검색 기능이 있는 SQLite FTS5
• 하이브리드 회상 -- 적응형 혼합을 통한 FTS5 키워드 + 코사인 유사도: 임베딩이 긴 텍스트에서 정보를 잃기 때문에 의미론적 가중치는 0.50(짧은 콘텐츠) → 0.15(긴 콘텐츠)로 변합니다.
• 6가지 요소 회상 점수 -- FTS 관련성 + 우선순위 + 액세스 빈도 + 신뢰도 + 계층 부스트 + 최신성 감쇠
• 자동 승격 -- 5회 이상 액세스된 메모리는 중기에서 장기로 승격
• TTL 연장 -- 각 회상 시 만료 연장(단기 +1시간, 중기 +1일)
• 우선순위 강화 -- 10회 액세스마다 +1 (최대 10)
• 모순 감지 -- 기존 메모리와 충돌하는 메모리를 저장할 때 경고
• 중복 제거 -- 제목+네임스페이스에 대한 upsert, 계층은 절대 다운그레이드되지 않음
• 신뢰도 점수 -- 순위에 반영되는 0.0-1.0 확실성

구성

• 네임스페이스 -- 프로젝트별로 메모리 격리(git 원격에서 자동 감지)
• 메모리 연결 -- 유형화된 관계: related_to, supersedes, contradicts, derived_from, reflects_on(재귀 학습 작업 1/8), derives_from(WT-1-A 원자화), decomposes_into, depends_on, advances -- v0.8.0에서 9가지 변형
• 통합 -- 여러 메모리를 단일 장기 요약으로 병합
• 자동 통합 -- 네임스페이스+태그별 그룹화, 임계값 초과 그룹 자동 병합
• 모순 해결 -- 한 메모리를 다른 메모리를 대체하는 것으로 표시, 패자 강등
• 패턴별 삭제 -- 네임스페이스 + FTS 패턴 + 계층별 대량 삭제
• 소스 추적 -- 출처 추적: 사용자, claude, 후크, api, cli, 가져오기, 통합, 시스템
• 에이전트 신원(NHI) -- 모든 메모리는 업데이트/중복 제거/가져오기/동기화/통합 전반에 걸쳐 심층 방어 불변성을 갖춘 metadata.agent_id(주장된 신원)을 전달합니다. 에이전트별로 list/search 필터링
• 태깅 -- 필터 지원이 포함된 쉼표로 구분된 태그

인터페이스

• 92개 HTTP 라우트 (78개 고유 경로) -- 127.0.0.1:9077에서 완전한 REST API 제공 (모든 AI 또는 도구와 연동 가능)
• 89개 CLI 하위 명령어 (--features sal 또는 --features sal-postgres 하위) (기본 빌드 기준 87개) -- 동일한 기능을 갖춘 완전한 CLI
• 101개 MCP 도구 (전체 프로필 기준; 기본값 7개; Profile::full().expected_tool_count() 대비 검증 완료) -- 모든 MCP 호환 AI를 위한 네이티브 통합
• 대화형 REPL 셸 -- 컬러 출력으로 회상, 검색, 목록, 가져오기, 통계, 네임스페이스, 삭제 지원
• JSON 출력 -- 모든 CLI 명령어에 --json 플래그 제공
• 분산 조정 (v0.8.0 Pillar-1 + Pillar-2) -- 액션 DAG(memory_action_*), 단일 소유자 임대(memory_lease_*), Ed25519 서명 신호(memory_signal_*), 증명된 체크포인트(memory_checkpoint_*), 매개변수화된 루틴(memory_routine_*), 그리고 Goal/Plan/Step 유형 인지 생명주기. docs/coordination.md 참조.

운영

• 멀티 노드 동기화 -- 데이터베이스 파일 간 풀, 푸시 또는 양방향 병합
• 가져오기/내보내기 -- 메모리 링크를 보존하는 완전한 JSON 왕복
• 가비지 컬렉션 -- 30분마다 자동 백그라운드 만료
• 정상 종료 -- SIGTERM/SIGINT 시 WAL 체크포인트를 생성하여 깔끔하게 종료
• 심층 상태 확인 -- DB 접근성 및 FTS5 무결성 검증
• 셸 자동 완성 -- bash, zsh, fish 지원
• 매뉴얼 페이지 -- ai-memory man 명령어로 roff를 stdout으로 생성
• 시간 필터 -- 목록 및 검색 시 --since/--until 사용
• 사람이 읽기 쉬운 경과 시간 -- CLI 출력에 "2시간 전", "3일 전" 등으로 표시
• 컬러 CLI 출력 -- ANSI 등급 레이블(빨강/노랑/초록), 우선순위 막대, 굵은 제목, 청록색 네임스페이스

품질

• 전체 표면에 걸쳐 약 10,000개 테스트 -- src/ 하위에 약 6,712개의 #[test]/#[tokio::test] 속성 (5,759개 #[test] + 953개 #[tokio::test]) 및 tests/ 하위에 약 3,362개 (2,138개 #[test] + 1,224개 #[tokio::test]), v0.6.4 시대의 약 2,400개 테스트 기준선(라이브러리 1,960개 + 통합 211개 + mcp_integration 16개 + webhook_http_parity 4개 + recipe_contract 16개 + 기타 바이너리 대상 약 150개)에서 증가. 라인 커버리지는 ≥92% 프로젝트 기준 이상 유지; v0.6.4 순 신규 모듈은 100% (sizes.rs), 99.50% (profile.rs), 97.58% (cli/audit.rs), 97.05% (cli/doctor.rs), 92.56% (handlers.rs), 92.26% (cli/install.rs). v0.6.3.x 기준선(1,809 / 93.08% 및 1,886 / 93.84%)은 증거 페이지에 동결된 상태로 유지; v0.6.4 지표는 릴리스 노트 및 테스트 허브 캠페인에 있음. 경험적 NHI 발견 수락은 발견 게이트에 의해 별도로 입증됨 (T1–T4 매트릭스 vs. 실시간 xAI Grok 4.3, 6/6 통과, 게이트 그린).
• LongMemEval 벤치마크 -- ICLR 2025 LongMemEval-S 데이터셋에서 97.8% R@5 (489/500), 99.0% R@10, 99.8% R@20. R@20에서 499/500. 순수 FTS5 키워드는 2.2초 만에 97.0% R@5 달성 (232 q/s). LLM 쿼리 확장으로 97.8% R@5까지 향상. 클라우드 API 비용 제로. 벤치마크 세부 정보 참조.
• MCP 프롬프트 -- recall-first 및 memory-workflow 프롬프트는 AI 클라이언트가 사전 예방적으로 메모리를 사용하도록 가르침
• TOON 기본값 -- 회상/목록/검색 응답은 기본적으로 TOON 압축 형식 사용 (JSON 대비 79% 더 작음)
• Criterion 벤치마크 -- 1K 규모에서 삽입, 회상, 검색
• GitHub Actions CI/CD -- Ubuntu + macOS에서 fmt, clippy, 테스트, 빌드, 태그 시 릴리스

커버리지 하한선 (하드 CI 게이트)

Code Coverage 작업은 필수 상태 확인입니다. CI는 모든 PR에 대해 두 가지 불변 조건을 재확인합니다: >= 90% 라인의 절대 하한선(현재 측정치를 가장 가까운 5%로 내림하여 설정한 치명적 회귀 방지 장치) 및 0.5% 여유 윈도우를 둔 .coverage-baseline에 고정된 값에 대한 래칫(일상적인 시행). 커버리지를 높이는 PR은 동일한 커밋에서 기준선 파일을 올려 향후 PR이 새로운 하한선의 혜택을 받도록 해야 합니다. 0.5% 이상 회귀하는 PR은 병합이 차단됩니다. 현재 측정치: 93.13% 라인.

토큰 예산 게이트 (하드 CI 게이트, v0.7 C5)

token-budget 워크플로우는 필수 상태 확인입니다. 모든 PR에 대해 cl100k_base로 측정된 세 가지 불변 조건을 시행합니다:

• 도구당 1500 토큰 상한 -- 단일 MCP 도구의 직렬화된 스키마(이름 + 설명 + inputSchema)가 1500 cl100k_base 토큰을 초과할 수 없습니다.
• 전체 프로필 정직 범위 (5K-8K) -- v0.6.4 백스톱으로, 병리적 축소(실수로 도구를 누락하는 경우)를 감지하기 위해 유지됩니다.
• 전체 프로필 하드 상한 (v0.7 C5, D1.6/D1.7 이후 상향) -- --profile full 하의 트리밍된 tools/list 페이로드는 11,000 cl100k_base 토큰을 초과할 수 없습니다 (tests/token_budget_guard.rs의 TRIMMED_FULL_PROFILE_CEILING_TOKENS; 원래 C5 목표는 D1.6 이전 수동 코딩된 스키마 대비 3500이었습니다 — schemars 파생 D1.6/D1.7 확장으로 고정 상한이 올라갔습니다). C2(문서 필드 분할), C3(반복되는 스키마 상용구 축소) 및 C4(거의 사용되지 않는 선택적 매개변수 숨기기)가 원래 압축을 주도했습니다. 이 게이트는 표면을 확장하는 향후 PR이 다른 곳에서 예산을 회수하도록 강제합니다. 도구별 비용을 보려면 ai-memory doctor --tokens --raw-table을 검사하십시오. .github/workflows/token-budget.yml 및 docs/v0.7/schema-compaction-audit.md 참조.

ML 및 LLM 종속성 (시맨틱 티어 이상)

• candle-core, candle-nn, candle-transformers -- 네이티브 Rust 추론을 위한 Hugging Face Candle ML 프레임워크
• hf-hub -- Hugging Face Hub에서 모델 다운로드
• tokenizers -- 텍스트 전처리를 위한 Hugging Face 토크나이저
• instant-distance -- 근사 최근접 이웃 검색
• reqwest -- LLM 백엔드 통신을 위한 HTTP 클라이언트 (스마트/자율 티어 — #1067에 따라 모든 제공자: Ollama, xAI, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Qwen, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks, LMStudio, vLLM, llama.cpp 서버)

아키텍처

벤치마크

ICLR 2025 LongMemEval-S 데이터셋(500개 질문, 6개 카테고리)에서 평가되었습니다. 순수 FTS5 키워드 티어는 2.2초 만에 97.0% R@5를 달성합니다. LLM 쿼리 확장(스마트 티어)은 97.8% R@5까지 끌어올립니다. 모든 추론은 로컬에서 실행되므로 클라우드 API 호출 및 비용이 전혀 발생하지 않습니다.

성능 예산 (v0.6.4)

모든 릴리스는 핫 경로 작업에 대해 게시된 p95/p99 예산과 함께 제공되며, 측정된 p95가 예산을 10% 이상 초과하는 PR을 실패시키는 CI 게이트가 있습니다. 목표는 M4 레퍼런스 하드웨어에 맞춰 조정되었습니다. 전체 표와 방법론은 PERFORMANCE.md에 있습니다.

로컬에서 동일한 워크로드 실행:

ai-memory bench                      # human-readable table
ai-memory bench --json               # machine-parseable

기반은 v0.6.3.x → v0.6.4에서 변경되지 않았습니다 (quiet-tools 릴리스는 다른 핫 경로가 아닌 더 작은 기본 도구 표면을 제공합니다). 여기의 p99 목표는 다음 전용 소크 기간까지 정보 제공용으로 유지됩니다. 최신 소크 증거는 테스트 허브에 있습니다.

통합 방법

MCP (기본 -- MCP 호환 AI 플랫폼용)

MCP가 권장되는 통합 방식입니다. AI는 글루 코드 없이 기본적으로 광고되는 7개의 네이티브 메모리 도구(원래 5개 + memory_load_family + memory_smart_load; 그리고 항상 켜져 있는 memory_capabilities 부트스트랩)를 얻습니다. 호출 가능한 다른 93개 도구(Profile::full().expected_tool_count() 대비 검증되고 src/mcp/registry.rs의 const_count_matches_full_profile에 의해 고정된 101개의 광고 항목)는 --profile graph|admin|power|full 또는 memory_capabilities --include-schema family=<name>을 통한 런타임 확장을 통해 접근 가능합니다. AI 플랫폼 구성에서 MCP 서버를 설정하십시오:

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp"]
    }
  }
}

HTTP API (범용 -- 모든 AI 또는 도구용)

REST API 접근을 위해 HTTP 서버를 시작하십시오. HTTP 호출을 할 수 있는 모든 AI, 스크립트 또는 자동화가 이를 사용할 수 있습니다:

ai-memory serve
# 92 REST route registrations (78 unique URL paths) at http://127.0.0.1:9077/api/v1/

CLI (범용 -- 스크립팅 및 직접 사용용)

CLI는 독립형으로 작동하거나 셸 명령을 실행하는 AI 통합을 위한 빌딩 블록으로 작동합니다:

ai-memory store --tier long --title "Architecture decision" --content "We use PostgreSQL"
ai-memory recall "database choice"
ai-memory search "PostgreSQL"

기능 티어

ai-memory는 시작 시 ai-memory mcp --tier <tier>로 선택되는 4가지 기능 티어를 지원합니다. 상위 티어는 디스크 및 RAM을 희생하여 ML 기능을 추가합니다:

기능 매트릭스

모든 기능이 최소 티어에 매핑됩니다. 각 티어는 하위 티어의 모든 기능을 포함합니다.

시맨틱 계층(기본값)은 Candle ML 프레임워크를 번들로 제공하며 최초 실행 시 all-MiniLM-L6-v2 모델을 다운로드합니다(~90 MB). 스마트 및 자율 계층에는 LLM 백엔드가 필요합니다 — #1067 (v0.7.0) 이후로는 로컬(Ollama, LMStudio, vLLM, llama.cpp 서버) 또는 모든 OpenAI 호환 원격 엔드포인트(xAI, OpenAI, OpenAI 심을 통한 Anthropic, Google Gemini, DeepSeek, Kimi, Qwen, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks)가 될 수 있습니다. 선택은 AI_MEMORY_LLM_BACKEND 환경 변수로 하며, 공급업체별 API 키는 XAI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY / DEEPSEEK_API_KEY / MOONSHOT_API_KEY / DASHSCOPE_API_KEY / 등을 통해 또는 표준 AI_MEMORY_LLM_API_KEY을 통해 설정합니다.

계층은 기능을 제어하며, 모델을 제어하지 않습니다 — 그리고 #1067 (v0.7.0) 이후로 계층은 기능을 제어할 뿐 공급업체도 제어하지 않습니다. --tier 플래그는 어떤 도구가 노출될지 제어합니다. LLM 백엔드 + 모델은 AI_MEMORY_LLM_BACKEND + AI_MEMORY_LLM_MODEL 환경 변수(또는 ~/.config/ai-memory/config.toml의 표준 [llm] 섹션 — v0.7.x 엔터프라이즈 스키마 및 마이그레이션 도구는 docs/CONFIG_SCHEMA.md 참조)를 통해 독립적으로 구성 가능합니다. 예를 들어, OpenAI 호환 별칭을 통해 xAI Grok 4에 대해 자율 계층(전체 101개 항목 표면 + 재순위 지정자)을 실행합니다:

# Quick path: env vars
export AI_MEMORY_LLM_BACKEND=xai
export AI_MEMORY_LLM_MODEL=grok-4.3
export XAI_API_KEY=xai-…   # or AI_MEMORY_LLM_API_KEY
ai-memory mcp --tier autonomous

# Enterprise path: ~/.config/ai-memory/config.toml (v0.7.x schema v2, #1146)
schema_version = 2
tier = "autonomous"

[llm]
backend     = "xai"
model       = "grok-4.3"
base_url    = "https://api.x.ai/v1"
api_key_env = "XAI_API_KEY"          # mutually exclusive with api_key_file;
                                     # inline `api_key = "..."` is REJECTED.

# Legacy v0.6.x shape — still works, deprecation WARN at load; run
# `ai-memory config migrate` to upgrade in place.
tier = "autonomous"
llm_model = "gemma3:4b"   # default Ollama model at v0.7.0

--tier 플래그는 MCP 인수에 반드시 전달되어야 합니다 -- AI 클라이언트가 서버를 시작할 때 config.toml 계층 설정은 사용되지 않습니다.

# Semantic is the default tier
ai-memory mcp

# Keyword -- FTS5 only, no models
ai-memory mcp --tier keyword

# Semantic -- hybrid recall with embeddings (explicit)
ai-memory mcp --tier semantic

# Smart -- adds LLM-powered query expansion, auto-tagging, contradiction detection
ai-memory mcp --tier smart

# Autonomous -- adds cross-encoder reranking
ai-memory mcp --tier autonomous

memory_capabilities 도구는 런타임에 활성 계층, 로드된 모델 및 사용 가능한 기능을 보고합니다.

MCP 도구

이 101개의 도구(전체 프로필; src/profile.rs의 Profile::full().expected_tool_count()을 통한 표준 개수)는 MCP 서버로 구성될 때 모든 MCP 호환 AI에서 사용할 수 있습니다(v0.6.4 고정 증거 페이지에는 63개 도구 기준이 나열되어 있으며, 아래 표는 대부분의 클라이언트가 일상적으로 사용하는 핵심 하위 집합을 문서화합니다):

HTTP API

127.0.0.1:9077에 92개의 경로 등록 / 78개의 고유 URL 경로. ai-memory serve로 시작합니다. 아래 표는 가장 일반적으로 사용되는 REST 엔드포인트를 보여줍니다. 전체 표면(거버넌스, 페더레이션, 구독, 지식 그래프, 할당량, 승인 SSE)은 docs/API_REFERENCE.md를 참조하십시오.

보안: HTTP 서버는 127.0.0.1에 바인딩되며 기본적으로 인증이 구성되지 않고 허용적인 CORS와 함께 제공됩니다. 모든 요청에 x-api-key 헤더를 요구하려면 config.toml에 api_key을 설정하고(레거시 ?api_key= 쿼리 매개변수 형식은 v0.7.0에서 더 이상 사용되지 않음 — #1574), 키 없는 시작을 강제로 거부하려면 AI_MEMORY_REQUIRE_API_KEY=1을 설정하십시오(#1458). 인증 없이 네트워크에 노출하지 마십시오(그리고 --tls-cert/--tls-key 또는 리버스 프록시를 통한 TLS를 선호합니다).

CLI 명령

--features sal 또는 --features sal-postgres 아래에 89개의 최상위 하위 명령이 있습니다(기본 빌드에서는 87개; 2개의 변형 차이는 Migrate + SchemaInit이며, 둘 다 src/daemon_runtime.rs::Command::{Migrate,SchemaInit}에 따라 #[cfg(feature = "sal")]로 제어됨; v0.6.4에서는 40개였습니다). 모든 명령에 대한 자세한 내용은 ai-memory <command> --help을, 전체 목록은 ai-memory --help을 실행하십시오.

최상위 ai-memory 바이너리는 전역 플래그도 허용합니다:

store 하위 명령은 추가 플래그를 허용합니다:

mcp 하위 명령은 추가 플래그를 허용합니다:

회상 점수

모든 회상 쿼리는 6가지 요소로 메모리 순위를 매깁니다:

score = (fts_relevance * -1)
      + (priority * 0.5)
      + (MIN(access_count, 50) * 0.1)
      + (confidence * 2.0)
      + tier_boost
      + recency_decay

메모리 계층

자동 동작

• 회상 시 TTL 연장: 단기 메모리는 +1시간, 중기 메모리는 +1일
• 자동 승격: 5회 이상 액세스된 중기 계층 메모리는 장기로 승격 (만료 해제)
• 우선순위 강화: 10회 액세스마다 우선순위가 1씩 증가 (최대 10)
• 모순 감지: 새 메모리가 동일한 네임스페이스의 기존 메모리와 충돌할 때 경고
• 중복 제거: 제목+네임스페이스에 대한 upsert; 업데이트 시 계층이 절대 다운그레이드되지 않음

구성 가능한 TTL

기본 TTL(단기 6시간, 중기 7일)은 [ttl] 섹션 아래의 ~/.config/ai-memory/config.toml에서 재정의할 수 있습니다:

[ttl]
short_ttl_secs = 21600      # short-tier TTL in seconds (default: 21600 = 6 hours)
mid_ttl_secs = 604800        # mid-tier TTL in seconds (default: 604800 = 7 days)
long_ttl_secs = 0            # long-tier TTL in seconds (default: 0 = never expires)
short_extend_secs = 3600     # TTL extension on recall for short-tier memories in seconds (default: 3600 = +1h)
mid_extend_secs = 86400      # TTL extension on recall for mid-tier memories in seconds (default: 86400 = +1d)

5개 필드 모두 선택 사항입니다 -- 기본값을 유지하려면 아무것도 생략하십시오. 해당 계층의 만료를 비활성화하려면 값을 0으로 설정하십시오. 값은 최대 10년으로 제한되며, 음수 연장 값은 0으로 제한됩니다.

참고: 구성은 프로세스 시작 시 한 번만 로드됩니다. config.toml 변경 사항을 적용하려면 ai-memory 프로세스(MCP 서버, HTTP 데몬 또는 CLI)를 다시 시작해야 합니다.

아카이브

가비지 컬렉션이 메모리를 만료시키면 영구 삭제 대신 아카이브할 수 있습니다. 아카이브된 메모리는 별도의 저장소로 이동되며 나중에 탐색, 복원 또는 제거할 수 있습니다.

구성

~/.config/ai-memory/config.toml에서 아카이브를 활성화합니다:

archive_on_gc = true   # archive expired memories instead of deleting them (default: true)

CLI 명령

archive 하위 명령으로 아카이브를 관리합니다:

ai-memory archive list                          # list archived memories
ai-memory archive list --namespace my-project   # filter by namespace
ai-memory archive restore <id>                  # restore an archived memory to active store
ai-memory archive purge --older-than-days 90     # permanently delete archives older than 90 days
ai-memory archive stats                         # show archive statistics

참고: 복원된 메모리는 expires_at이(가) 지워집니다(다음 TTL 할당까지 영구 상태가 됨).

MCP 도구

MCP 클라이언트는 네 가지 아카이브 도구를 사용할 수 있습니다:

HTTP 엔드포인트

보안

ai-memory는 모든 입력 경로에 걸쳐 강화 조치를 포함합니다:

• 트랜잭션 안전성 -- 모든 다단계 데이터베이스 작업은 트랜잭션을 사용합니다. 실패 시 부분 쓰기가 발생하지 않습니다.
• FTS 인젝션 방지 -- 사용자 입력은 FTS5 쿼리에 도달하기 전에 정리됩니다. 특수 문자가 이스케이프 처리됩니다.
• 오류 정리 -- 내부 데이터베이스 경로 및 시스템 세부 정보가 오류 응답에서 제거됩니다. 클라이언트에는 구조화된 오류 유형(NOT_FOUND, VALIDATION_FAILED, DATABASE_ERROR, CONFLICT)이 표시됩니다.
• 본문 크기 제한 -- HTTP 요청 본문은 Axum의 DefaultBodyLimit를 통해 50MB로 제한됩니다.
• 대량 작업 제한 -- 대량 생성 엔드포인트는 리소스 고갈을 방지하기 위해 최대 배치 크기를 적용합니다.
• CORS -- 로컬호스트 개발 워크플로우를 위해 허용적인 CORS 레이어가 활성화됩니다.
• 입력 유효성 검사 -- 모든 쓰기 경로는 제목 길이, 콘텐츠 길이, 네임스페이스 형식, 소스 값, 우선순위 범위(1-10), 신뢰도 범위(0.0-1.0), 태그 형식, 계층 값, 관계 유형 및 ID 형식을 검증합니다.
• 동기화 시 링크 유효성 검사 -- 동기화 작업 중 가져오기 전에 모든 링크(두 ID, 관계 유형, 자체 링크 없음)가 검증됩니다.
• 스레드 안전 색상 -- 터미널 색상 감지는 안전한 동시 접근을 위해 AtomicBool을(를) 사용합니다.
• 로컬 전용 HTTP -- HTTP 서버는 기본적으로 127.0.0.1에 바인딩됩니다. 네트워크에 노출되지 않습니다.
• WAL 모드 -- 쓰기 중 안전한 동시 읽기를 위한 SQLite Write-Ahead Logging.

문서

라이선스

Copyright 2026 AlphaOne LLC.

Apache License, Version 2.0 (이하 "라이선스")에 따라 사용이 허가됩니다. 라이선스를 준수하는 경우를 제외하고 이 파일을 사용할 수 없습니다. 라이선스 사본은 다음에서 얻을 수 있습니다.

http://www.apache.org/licenses/LICENSE-2.0

관련 법률에서 요구하거나 서면으로 동의한 경우를 제외하고, 라이선스에 따라 배포되는 소프트웨어는 명시적이든 묵시적이든 어떠한 종류의 보증이나 조건 없이 "있는 그대로" 배포됩니다. 라이선스에 따른 특정 언어의 권한 및 제한 사항은 라이선스를 참조하십시오.