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개 수정 사항과 소규모 추가 기능 세트가 포함되었습니다. 주요 변경 사항은 보안 기본값 전환입니다: HTTP 직접 쓰기 시 에이전트 증명이 기본적으로 필요하며(#1751, #1985에 의해 표면 범위 지정) — 서명되지 않은 HTTP POST /api/v1/memories(+/bulk)는 운영자가 명시적 옵트아웃 AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0를 설정하지 않는 한 attest_level="claimed"로 처리되지 않고 거부(403 ATTESTATION_FAILED)됩니다. MCP memory_store 및 CLI store 표면은 운영자 역할 경로이며 기본적으로 허용적입니다(서명되지 않은 쓰기는 claimed로 처리됨). =1는 모든 표면에서 엄격 모드를 강제합니다. (v0.9.0 GA는 이를 모든 곳에서 요구하는 방식으로 제공했으나, MCP 호스트에서 충족할 수 없어 현재 릴리스에서 표면 범위로 수정되었습니다.) 이와 함께, 필수 훅 존재 시행 게이트가 이제 MCP 쓰기 경로(#1885) 와 HTTP 쓰기 경로(#1924) 모두에서 작동하여, 구성된 필수 훅이 한 표면에서는 건너뛰어질 수 있었던 무단 통과 간극을 해소합니다. 강화 작업은 또한 bulk_create 행별 증명 게이팅(#1919)을 닫고, 인바운드 페더레이션 PENDING 승인을 등록된 승인자 게이트를 통해 라우팅하며(#1920), team/unit/org 가시성 범위를 네임스페이스 계층 전체에 걸쳐 과도하게 넓지 않도록 강화하고(#1921), skill_register의 folder_path 가져오기를 심볼릭 링크 감옥으로 구성된 루트 아래로 제한합니다(#1923). 새로운 비argv 자격 증명 채널 — 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) 전반에서 하나의 동일한 API 뒤에 있는 두 개의 프로덕션 백엔드 — 임베디드 SQLite 및 PostgreSQL + Apache AGE — 에서 실행됩니다. 증명 및 훅 시행 전환을 제외한 모든 것은 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) 전반에서 하나의 동일한 API 뒤에 있는 두 개의 프로덕션 백엔드 — 임베디드 SQLite 및 PostgreSQL + Apache AGE — 에서 실행됩니다. 모든 것은 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 + 7th-form 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() 단계 부문(파일 이름 카운터는 논리 스키마 버전보다 뒤처지는데, 두 단계 부문 모두 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".

기본 보안 강화

• HTTP 직접 쓰기 표면에서 기본적으로 에이전트 증명 필요 (#1751, #1985에 의해 표면 범위 지정). AI_MEMORY_REQUIRE_AGENT_ATTESTATION는 표면별 컴파일 기본값을 가진 3가지 상태입니다: 설정되지 않음 → HTTP 직접 쓰기(POST /api/v1/memories + /bulk, 거부됨 403 ATTESTATION_FAILED)에서는 필수, MCP memory_store 및 CLI store 운영자 역할 표면에서는 허용적(서명되지 않은 쓰기는 attest_level="claimed"로 기록됨); =1은 모든 곳에서 엄격 모드를 강제하고, =0은 모든 곳에서 허용적 모드를 강제합니다. 제시되었지만 위조된 서명은 표면에 관계없이 모든 곳에서 거부됩니다. 쓰기에 서명하거나(ai-memory store --sign 및 ai-memory agents bind-key를 통해 바인딩된 키 쌍 사용) =0 옵트아웃을 사용하세요. (v0.9.0 GA는 이를 모든 곳에서 필수로 제공하여 MCP 호스트에서 충족할 수 없었습니다 — #1981 참조; #1985에 의해 표면 범위 지정으로 수정됨.)
• 이중 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/저장소 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).

타입 인지 (기둥-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 작업은 허용적 선택 요청 필드만 추가.

연합 강화, 기본적으로 안전하게

피어 등록 기본 활성화(#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).

기둥-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)

• Form 1 — 온라인 중복 제거 및 합성 (이슈 #754). 단일 배치 액션 방출 LLM 호출이 저장 경로에서 v0.6.x 쌍별 분류기를 대체. 네임스페이스 표준에서 legacy_per_pair_classifier = true을 통해 레거시 예/아니오로 다시 선택 가능.
• Form 2 — 동기식 임베드 전 분해 (이슈 #755). 새로운 memory_atomise 도구 + auto_atomise_mode = Synchronous|Deferred|Off 사전 저장 훅. 큐레이터가 리콜이 보기 전에 긴 쓰기를 2~10개의 원자적 명제로 분해. docs/atomisation.md 참조.
• Form 3 — 다단계 수집 오케스트레이터 (이슈 #756). memory_ingest_multistep가 결정적 Jaccard+FTS 도우미를 프롬프트 캐시 안정 LLM 단계를 통해 스레드 처리. docs/multistep-ingest.md + cookbook/multistep-ingest/01-two-phase.sh 참조.
• Form 4 — 사실 출처 (이슈 #757). 인용 + 소스 URI + 원자 단위 범위가 기존 memory_store / memory_atomise 페이로드에 탑재. docs/provenance.md 참조.
• Form 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 참조.
• Form 6 — MemoryKind Batman 어휘 (이슈 #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 참조.
• 7th-form — 에이전트-외부 Layer-4 연결 (Option-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 참조.
• 운영자 방법 — Forms 1–6 + 7th를 가능 상태에서 활성 상태로 전환 (이슈 #800). 7단계 레시피(운영자 키 생성 → 서명 시드 → R001–R004 활성화 → 큐레이터 데몬 → 선택적 리플렉션 패스 → 네임스페이스 정책), launchd / systemd / Task-Scheduler 영구화, 검증 블록, 롤백 경로. 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 논스, method+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 동사. 벤치마크 기준 — 깊이=5에서 AGE p95가 CTE p95보다 30% 이상 빨라야 합니다. 운영자 방법: docs/postgres-age-guide.md. 마이그레이션 실행서: docs/migration-v0.7.0-postgres.md.
• Capabilities 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. 동기화 데몬 -- 인스턴스 간 쿼럼 기반 피어 페더레이션. W-of-N 쓰기(기본 과반수), 벡터 클록 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)은 많은 에이전트가 병렬로 쓸 때 피어 간 W-of-N 일관성을 처리합니다. 큐레이터 데몬은 떼가 공유 코퍼스에 기록할 때 노이즈로 저하되는 것을 방지합니다. 웹훅 구독(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를 포함합니다. 이는 모든 작업(업데이트, 중복 제거, 가져오기, 동기화, 통합)에서 살아남는 비인간 아이덴티티 마커입니다. 모든 재현율 결과는 기본적으로 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은 주장된 아이덴티티이므로 이것만으로 보안 결정을 내리지 마십시오. 저장소 경로 에이전트 증명은 HTTP 직접 쓰기 표면에서 기본적으로 필수입니다(#1751, #1985에 의해 표면 범위 지정): 서명되지 않은 HTTP POST /api/v1/memories (+/bulk)은 attest_level = "claimed"에 도달하는 대신 거부(403 ATTESTATION_FAILED)됩니다. 단, 운영자가 명시적 옵트아웃 AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0을 설정한 경우는 예외입니다. MCP memory_store 및 CLI store 운영자-액터 표면은 기본적으로 허용적입니다(서명되지 않은 쓰기는 claimed에 도달). =1는 모든 표면에서 엄격 모드를 강제합니다. 암호화 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)과 추가 전용 signed_events 감사 체인이 있는 이전에 예약된 memory_links.signature 필드. 전체 출처 계약은 에이전트 아이덴티티 페이지와 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(로컬호스트에서 92개 라우트 등록 / 78개 고유 URL 경로)와 CLI(--features sal 또는 --features sal-postgres 아래 89개 하위 명령; 기본 빌드에서 87개(post-#1389 L2 RecoverPreviousSession for cross-session context rehydration + #1443 Expand for the ai-memory expand query-expansion surface + #1598 Reembed for the ai-memory reembed vector-space migration surface); SSOT pinned by ai_memory::EXPECTED_CLI_SUBCOMMANDS_DEFAULT + EXPECTED_CLI_SUBCOMMANDS_SAL + the mechanical tests/cli_subcommand_count_invariant.rs parity test)가 범용 액세스를 제공합니다 -- 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개(교차 세션 컨텍스트 재수화를 위한 #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 패턴 + 계층별 대량 삭제
• 소스 추적 -- 출처 추적: user, claude, hook, api, cli, import, consolidation, system
• 에이전트 신원(NHI) -- 모든 메모리는 업데이트/중복 제거/가져오기/동기화/통합 전반에 걸쳐 심층 방어 불변성을 가진 metadata.agent_id(주장된 신원)을 전달합니다. 에이전트별로 list/search 필터링
• 태깅 -- 필터 지원이 포함된 쉼표로 구분된 태그

인터페이스

• 92개 HTTP 경로(78개 고유 경로) -- 127.0.0.1:9077의 전체 REST API(모든 AI 또는 도구와 작동)
• --features sal 또는 --features sal-postgres 아래 89개 CLI 하위 명령(기본 빌드에서 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가 stdout으로 roff 생성
• 시간 필터 -- 나열 및 검색 시 --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개 lib + 211개 통합 + 16개 mcp_integration + 4개 webhook_http_parity + 16개 recipe_contract + 기타 바이너리 대상 전반에 걸친 약 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 매트릭스 대 라이브 xAI Grok 4.3, 6/6 통과, GATE GREEN)에 의해 별도로 입증되었습니다.
• LongMemEval 벤치마크 -- ICLR 2025 LongMemEval-S 데이터 세트에서 97.0% R@5 순수 FTS5 키워드(LLM 독립적, 2.2초, 232 q/s, API 비용 제로); 현재 세대 Gemma 4 모델을 사용한 LLM 쿼리 확장은 97.2% R@5 / 99.6% R@10 / 99.8% R@20을 측정합니다(클라우드 API 환경; 이전 gemma3:4b 97.8% 수치는 #1975에 따라 헤드라인에서 폐기됨). 벤치마크 세부 정보 참조.
• 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 독립적, 완전 로컬, 클라우드 API 호출 제로, 비용 제로. LLM 쿼리 확장(스마트 계층)은 현재 세대 Gemma 4 모델(클라우드 API 환경)로 97.2% R@5를 측정합니다.

벤치마크 모델 참고 사항 (2026-07-10 업데이트, #1975 판결): 과거 97.8% R@5 스마트 계층 수치는 Gemma 3 4B(여전히 컴파일된 기본 확장 모델)로 측정되었으며 헤드라인에서 제외되었습니다. 게시된 현재 세대 기준은 측정된 OpenRouter Gemma 4 실행입니다: 97.2% R@5 / 99.6% R@10 / 99.8% R@20 (2026-05-31, 500개 질문, 확장 실패 0회). 로컬 Ollama Gemma-4 수치는 존재하지 않습니다 — 참조 벤치마크 호스트는 CPU 전용이므로 유효한 전체 프로토콜 로컬 실행이 불가능합니다(#1983 참조). 로컬 GPU 재실행은 v1.0 이후에도 계속 열려 있습니다. 키워드 계층 97.0% R@5는 LLM 독립적이며 영향을 받지 않습니다.

성능 예산 (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개의 호출 가능한 도구(101개의 광고 항목 — Profile::full().expected_tool_count()에 대해 검증되고 src/mcp/registry.rs의 const_count_matches_full_profile에 의해 고정됨)는 --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 shim을 통한 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 클라이언트가 사용할 수 있는 4개의 보관 도구:

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

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