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개 레인 적대적 검토에서 나온 49건의 수정(#1885–#1935)과 소규모 추가 기능 세트. 주요 변경 사항은 보안 기본값 전환입니다: HTTP 직접 쓰기에서 에이전트 증명이 기본적으로 필수(#1751, #1985로 표면 범위 지정) — 서명되지 않은 HTTP POST /api/v1/memories(+/bulk)는 403 ATTESTATION_FAILED에 거부되며 attest_level="claimed"에 저장되지 않습니다. 단, 운영자가 명시적 옵트아웃 AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0를 설정하지 않는 한. 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). 추가 기능 작업: 에이전트 작성 스킬 메모리 with 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 라우트 등록 (78 고유 URL 경로), --features sal/sal-postgres 아래 89 CLI 하위 명령 (87 기본 빌드), 9 유형화된 MemoryLink 관계, 28개 필드 Memory. 동일한 API 뒤의 두 프로덕션 백엔드 — 임베디드 SQLite 및 PostgreSQL + Apache AGE — 데스크톱, 서버 및 온디바이스(iOS + Android)에서 실행. 증명 및 후크 강제 전환을 제외한 모든 것이 v0.8.1에 추가적이며, 이는 기본적으로 안전한 주요 변경 사항입니다 — 업그레이드 전에 검토하세요. 전체 변경 로그: CHANGELOG.md §"[0.9.0] — 2026-07-08".

v0.8.0 (distributed-coordination) — 이전 릴리스. 메모리 기반이 조정 기반이 되는 릴리스입니다. #1709의 분산 조정 메커니즘을 추가합니다: 실제 상태 머신이 있는 유형화된 액션 DAG (memory_action_*), 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 라우트 등록 (78 고유 URL 경로), 83/85 CLI 하위 명령, 9 유형화된 MemoryLink 관계, 27개 필드 Memory. 동일한 API 뒤의 두 프로덕션 백엔드 — 임베디드 SQLite 및 PostgreSQL + Apache AGE — 데스크톱, 서버 및 온디바이스(iOS + Android)에서 실행. 모든 것이 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 + 조정 보안 점검)을 포함합니다. 기반은 더 표현력이 풍부해지고(capabilities v3, 명명된 로더 도구, 압축된 스키마, Batman MemoryKind 어휘, persona/atomisation/multistep-ingest 프리미티브) 암호학적으로 신뢰할 수 있게 됩니다(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 Memory 형태에 대해 무손실이 되도록 함; 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 만료 mid/short 행에 티어 기본 만료를 백필하여 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 재작성과 짝을 이루는 복합 list/archive 정렬 인덱스(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 인덱스를 추가하여 search/recall 형태가 일치하고 일치하는 각 행에 대해 tsvector를 다시 계산하는 대신 미리 계산된 컬럼에서 AND 순위를 매기도록 함 — 레거시 memories_content_fts 표현식 인덱스는 제거되고 sqlite 트윈은 FTS5가 이미 인덱스된 텍스트를 구체화하므로 버전 스탬프 no-op), 새로운 ai-memory schema-init CLI 동사, 그리고 6-요소 recall 점수 동등성. v0.6.4 기본 표면은 항상 켜진 로더 2개가 추가되어 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는 표면별 컴파일 기본값이 있는 삼중 상태입니다: 설정 안 됨 → 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 store-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 모드). 순위 동작을 아직 변경하지 않고 recall 피드백 루프를 닫습니다.
• 메모리 파생 계보 DAG (memory_lineage, 스키마 v78, #1859). MCP와 새로운 GET /api/v1/memories/{id}/lineage HTTP 경로를 통해 어떤 메모리가 어떤 메모리에서 파생되었는지 추적합니다.
• 벡터 검색 최소 옵트인 슬라이스 (#1005; 전체 기반은 #1860으로 연기).
• 물리적 CPU 수에 맞춰진 Reranker 워커 풀 (#1867) 및 recall은 기본적으로 PURE (#1869 — recall 핫 경로에서 쓰기 버스트를 제거).
• 추가 전용 스파인 + 서명 계층 분리: 모든 변형 사이트가 서명된 개정 리프로 라우팅(#1823), Recorder/Judge/Stopper 3-키 서명 분리(#1826), macaroon 기능 토큰 종단 간 연결(#1827), 회전 생존을 위한 서명된 ID 계보 키 승계 체인(#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)

• Actions — 의존성 DAG (스키마 v59). 상태 머신(pending → claimed → in_progress → done/failed/abandoned)을 가진 타입화된 액션 노드, 타입화된 DAG 엣지(requires / unlocks / blocks / gated_by / sibling), 그리고 다음 실행 가능한 노드를 가져오는 frontier/next 표면. 8개의 MCP 도구(memory_action_create / _get / _transition / _list / _add_edge / _edges / _frontier / _next).
• Leases — 단일 보유자, TTL 제한 클레임 (스키마 v59). 하트비트로 갱신되는 compare-and-swap 클레임(PRIMARY KEY on action_id = 한 번에 한 보유자)과 시간별 lease-sweeper. 4개의 MCP 도구(memory_lease_acquire / _renew / _release / _get).
• Signals — 타입화된, Ed25519 서명된 에이전트 간 메시지 (스키마 v60). 각각 서명 + 발신자 signer_pubkey를 포함하며 correlation_id / in_reply_to를 통해 스레드 처리. 5개의 MCP 도구(memory_signal_send / _read / _inbox / _thread / _ack).
• Checkpoints — 증명된 조건부 게이트 (스키마 v61). 조건이 해결될 때까지 차단하는 게이트; 해결은 직무 분리를 위해 제자리에서 자체 서명(Ed25519)되며, verify가 서명을 다시 확인. 4개의 MCP 도구(memory_checkpoint_create / _resolve / _query / _verify).
• Routines — 매개변수화된, 고정된, 재생 가능한 계획 (스키마 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 페더레이션 팬아웃(#1718)으로 HTTP 데몬(POST /api/v1/actions/{id}/transition, POST /api/v1/signals)에 미러링.

타입화된 인지 (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), 전환 재생 nonce(#1805), 그리고 아웃바운드 피어 인증서 지문 고정(#1678). 서로를 신뢰할 필요가 없는 이기종 플릿 — 업그레이드 전에 docs/v0.8.0/release-notes.md §"Federation hardening"의 보안 기본값 변경을 검토.

실제로 차단하는 거버넌스 (#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), 그리고 ai-memory verify-audit-trail CLI(§22 PE-8)는 signed_events 교차 행 해시 체인을 끝까지 순회.

스키마 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에서 제공된 dead 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은 비어 있고 데몬은 부팅 시 "continuing unsigned" 줄을 출력합니다. 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 재귀 학습 Task 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). /api/v1/approvals/stream 서버 전송 이벤트는 HMAC 논스, 메서드+pending_id 바인딩, 지연 이벤트 수 제거를 포함합니다 (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는 depth=5에서 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 그랜드슬램 웨이브

memory_reflect 기반 프리미티브와 네임스페이스 범위의 max_reflection_depth 상한(기본 3, Some(0)은 킬 스위치). 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-lite 병합, 피어 간 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줄 이상의 메모리 컨텍스트 비용을 지불하지 마세요.

에이전트 ID(NHI) — 모든 메모리는 누가 배웠는지 알려줍니다

ai-memory가 저장하는 모든 메모리는 metadata.agent_id — 모든 작업(업데이트, 중복 제거, 가져오기, 동기화, 통합)에서 유지되는 비인간 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은 주장된 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_links.signature 필드와 인바운드 검증을 위한 memory_verify(link_id) 및 추가 전용 signed_events 감사 체인. 전체 출처 계약은 에이전트 ID 페이지 및 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는 **Model Context Protocol (MCP)**을 지원하는 모든 AI 플랫폼과 통합됩니다. MCP는 AI 어시스턴트를 외부 도구 및 데이터 소스에 연결하기 위한 보편적 표준입니다.

MCP는 기본 통합 계층입니다. 아직 MCP를 기본 지원하지 않는 AI 플랫폼의 경우, HTTP API(localhost에서 92개 라우트 등록 / 78개 고유 URL 경로)와 CLI(--features sal 또는 --features sal-postgres 아래 89개 하위 명령어; 기본 빌드에서 87개(교차 세션 컨텍스트 재수화를 위한 #1389 이후 L2 RecoverPreviousSession + ai-memory expand 쿼리 확장 표면을 위한 #1443 Expand + ai-memory reembed 벡터 공간 마이그레이션 표면을 위한 #1598 Reembed); SSOT는 ai_memory::EXPECTED_CLI_SUBCOMMANDS_DEFAULT + EXPECTED_CLI_SUBCOMMANDS_SAL + 기계적 tests/cli_subcommand_count_invariant.rs 패리티 테스트로 고정됨)가 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를 다운로드하고 압축을 푼 다음, Xcode 프로젝트의 "Frameworks, Libraries, and Embedded Content" 아래에 AiMemory.xcframework를 끌어다 놓습니다.
• 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 클라이언트를 다시 시작하세요. 이제 부팅 시 7개의 기본 메모리 도구가 광고됩니다(런타임 확장 또는 --profile full을 통해 도달 가능한 101개의 광고 항목) — 대화 중에 기본적으로 메모리를 저장하고 회상할 수 있습니다.

SDK

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

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(Model Context Protocol) 도구 서버로 실행됩니다 — AI가 기본적으로 통신하는 백그라운드 프로세스입니다. AI가 중요한 것을 배우면 저장합니다. 컨텍스트가 필요하면 6요소 점수 알고리즘으로 순위가 매겨진 관련 메모리를 회상합니다. 메모리는 세 가지 계층으로 존재합니다:

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

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

MCP 외에도 ai-memory는 전체 HTTP REST API(포트 9077에서 92개 라우트 등록 / 78개 고유 URL 경로)와 완전한 CLI(--features sal 또는 --features sal-postgres 아래 89개 하위 명령; 기본 빌드에서 87개(교차 세션 컨텍스트 재수화를 위한 #1389 L2 RecoverPreviousSession + ai-memory expand 쿼리 확장 표면을 위한 #1443 Expand + ai-memory reembed 벡터 공간 마이그레이션 표면을 위한 #1598 Reembed); SSOT는 ai_memory::EXPECTED_CLI_SUBCOMMANDS_{DEFAULT,SAL} + 기계적 tests/cli_subcommand_count_invariant.rs 패리티 테스트로 고정)를 제공하여 직접 상호 작용, 스크립팅 및 모든 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)
• 모순 감지 — 기존 메모리와 충돌하는 메모리를 저장할 때 경고
• 중복 제거 — 제목+네임스페이스에서 업서트, 계층은 절대 다운그레이드되지 않음
• 신뢰도 점수 — 순위에 반영되는 0.0-1.0 확실성

조직

• 네임스페이스 — 프로젝트별 메모리 격리(git 원격에서 자동 감지)
• 메모리 연결 — 유형화된 관계: related_to, supersedes, contradicts, derived_from, reflects_on(재귀 학습 Task 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
• 에이전트 ID(NHI) — 모든 메모리는 업데이트/중복 제거/가져오기/동기화/통합 전반에 걸쳐 심층 방어 불변성을 갖는 metadata.agent_id(주장된 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는 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 lib + 211 integration + 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 발견 수용은 Discovery Gate(라이브 xAI Grok 4.3에 대한 T1–T4 매트릭스, 6/6 PASS, GATE GREEN)에 의해 별도로 입증됨.
• LongMemEval 벤치마크 — ICLR 2025 LongMemEval-S 데이터셋에서 97.0% R@5 순수 FTS5 키워드(LLM 독립, 2.2초, 232 q/s, API 비용 0). 현재 세대 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, test, build, 태그에서 릴리스

적용 범위 하한선 (하드 CI 게이트)

Code Coverage 작업은 필수 상태 확인입니다. CI는 모든 PR에 대해 두 가지 불변 조건을 다시 확인합니다: 라인 기준 90% 이상의 절대 하한선(치명적 회귀 방지 백스톱, 현재 측정값을 가장 가까운 5% 단위로 내림하여 설정) 및 .coverage-baseline에 고정된 값에 대한 래칫(0.5% 허용 오차 창, 일상적 적용). 적용 범위를 높이는 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 호출 0회, 비용 0. 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가 함께 제공됩니다. config.toml에서 api_key를 설정하여 모든 요청에 x-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으로 제한)
• 모순 감지: 새 기억이 동일한 네임스페이스의 기존 기억과 충돌할 때 경고
• 중복 제거: 제목+네임스페이스에 대한 업서트; 업데이트 시 계층은 절대 강등되지 않음

구성 가능한 TTL

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

[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)

다섯 필드는 모두 선택 사항입니다 — 생략하면 기본값을 유지합니다. 값을 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 -- localhost 개발 워크플로우를 위해 허용적인 CORS 레이어가 활성화되어 있습니다
• 입력 검증 -- 모든 쓰기 경로는 제목 길이, 콘텐츠 길이, 네임스페이스 형식, 소스 값, 우선순위 범위(1-10), 신뢰도 범위(0.0-1.0), 태그 형식, 계층 값, 관계 유형 및 ID 형식을 검증합니다
• 동기화 시 링크 검증 -- 동기화 작업 중 가져오기 전에 모든 링크(양쪽 ID, 관계 유형, 자기 링크 금지)가 검증됩니다
• 스레드 안전 색상 -- 터미널 색상 감지는 안전한 동시 액세스를 위해 AtomicBool을 사용합니다
• 로컬 전용 HTTP -- HTTP 서버는 기본적으로 127.0.0.1에 바인딩되며, 네트워크에 노출되지 않습니다
• WAL 모드 -- SQLite Write-Ahead Logging을 사용하여 쓰기 중 안전한 동시 읽기를 지원합니다

문서

라이선스

저작권 2026 AlphaOne LLC.

Apache License, Version 2.0(이하 "라이선스")에 따라 라이선스가 부여됩니다. 라이선스를 준수하지 않는 한 이 파일을 사용할 수 없습니다. 라이선스 사본은 다음에서 얻을 수 있습니다.

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

해당 법률에 의해 요구되거나 서면으로 동의하지 않는 한, 이 라이선스에 따라 배포되는 소프트웨어는 "있는 그대로" 배포되며, 명시적이든 묵시적이든 어떠한 종류의 보증이나 조건도 없이 배포됩니다. 라이선스에 따른 권한 및 제한 사항을 확인하려면 라이선스 본문을 참조하십시오.