hyxnj666-creator/ai-memory

AI 에디터의 채팅 기록을 타입이 지정된 Markdown + AGENTS.md 규칙으로 변환합니다 — 로컬 우선(local-first), Git 추적 가능, .remember() 호출 제로.

npx ai-memory-cli extract # 에디터의 채팅 기록을 읽어 타입이 지정된 Markdown으로 변환
npx ai-memory-cli rules --target agents-md # → AGENTS.md 생성 (Cursor / Claude / Windsurf / Copilot / Codex 모두 읽을 수 있음)
npx ai-memory-cli recall "OAuth" # 모든 결정의 전체 Git 계보(lineage) 표시
...

다른 모든 "AI 메모리 (AI memory)" 도구들은 remember() API로 시작하며 코드에 계측(instrument)할 것을 요구합니다. ai-memory는 에디터의 채팅 기록을 직접 읽습니다 — Cursor, Claude Code, Windsurf, Copilot Chat, Codex CLI — 그리고 이를 AGENS.md를 통해 모든 AI 에디터가 다시 읽을 수 있는 타입이 지정되고 Git 추적이 가능한 Markdown으로 변환합니다. 새로 배워야 할 API 접점도 없고, 세션 사이에 유지해야 할 런타임 메모리 저장소도 없습니다. 기본적으로 로컬 우선(Local-first) 방식입니다. 대화 내용은 절대 사용자의 기기를 떠나지 않습니다. 유일한 네트워크 호출은 추출을 위해 사용자가 설정한 LLM 제공업체로의 호출뿐입니다. 또는 완전히 오프라인으로 작동하기 위해 Ollama / LM Studio를 사용할 수도 있습니다.

다른 어디에서도 함께 찾아볼 수 없는 네 가지 요소가 있습니다. 처음 세 가지는 구조적이며, 네 번째는 다른 누구도 투자하지 않고 있는 엔지니어링 투자입니다.

• Zero (제로): 우리는 당신이 이미 작성한 것, 즉 디스크에 이미 존재하는 Cursor / Claude Code / Windsurf / Copilot Chat / Codex CLI 트랜스크립트(transcripts)를 읽습니다. 임포트할 SDK도 없고, 유지해야 할 런타임 메모리 저장소도 없습니다. 애플리케이션 코드에서 .remember() 보일러플레이트나 client.add(...) 호출이 필요한 mem0 / Letta / Zep / cortexmem과 비교해 보십시오.

• Native (네이티브): AGENTS.md 출력. ai-memory rules --target agents-md는 Cursor, Claude Code, Windsurf, Copilot, OpenAI Codex CLI가 모두 소비하는 도구 간 표준 규칙 파일을 작성합니다. 병합은 멱등성(idempotent)을 가집니다: <!-- ai-memory:managed-section start --> ... end --> 사이의 섹션만 수정되며, AGENTS.md에 직접 작성한 모든 내용은 바이트 단위로 그대로 보존됩니다.

도입 사례가 6만 개 이상의 저장소(repos)를 넘어섰으며, 현재 Linux Foundation의 관리 하에 있습니다 — 대부분의 프로젝트는 이를 처음부터 직접 작성하지만, 우리는 귀하의 대화 기록으로부터 이를 생성합니다. -
git 내의 일반 Markdown — 데이터베이스 없음. .ai-memory/

은 신뢰할 수 있는 단일 원천(source of truth)입니다: git diff를 통해 비교하고, 코드 리뷰(code-review)를 수행하며, 브랜치(branch)를 나누고, 되돌릴(revert) 수 있는 Markdown 파일들입니다. "git 추적 가능(git-trackable)" 메모리를 광고하는 다른 도구들은 자신들의 *내부 저장소(internal store)*에 대한 git 추적 스냅샷을 전송하지만, 우리는 사람이 읽을 수 있는 파일 형식을 제공하여 git이 모든 것을 관리하도록 합니다. 기기 간 동기화는 git pull로 이루어집니다. -
git 히스토리를 통한 타임머신 회상(Time-travel recall). ai-memory recall <query>는 모든 메모리의 커밋 단위(commit-by-commit) 전체 계보를 보여줍니다: 4월 1일에 결정 사항이 무엇이었는지, 4월 15일에는 무엇이었는지, 무엇이 변경되었고 누가 변경했는지를 보여줍니다. 다른 모든 메모리 도구는 "최신 버전"만을 반환하며, 대체된 이전 버전들은 조용히 덮어씌워집니다. 새로운 런타임 의존성(runtime dep)은 없습니다: recall은 10초의 타임아웃과 함께 귀하의 기존 git을 셸 명령(shells out)으로 호출합니다.

CCEB — Cursor Conversation Extraction Benchmark, gpt-4o-mini, 30개의 수동 큐레이션된 피스처(fixtures) (v1.1 확장):

지표 (Metric)	v1.1 (2026-04-27, 30 fixtures)	v1.0 / v2.5-01 (2026-04-26, 9 fixtures)	v2.4 (2026-04-25, 9 fixtures)
전체 F1 (Overall F1)	64.1% (P 56.8% / R 73.5%)	76.2% (P 66.7% / R 88.9%)	56.0% (P 43.8% / R 77.8%)
decision / issue F1	78.3% / 100%	75.0% / 100%	66.7% / 66.7%
architecture F1	72.7% (새로운 병목 현상(bottleneck) 회상)	100%	50%
노이즈 거부 (잡담 / 보류 / 가설) (Noise rejection)	100% — 4개의 노이즈 피스처 중 어떤 것에서도 환각(hallucinated)된 메모리 없음	100% (2 fixtures)	100% (2 fixtures)
실제 소요 시간 (Wall-clock)	239.7 s	47.9 s	70.5 s
비용 (Spend)	≈ $0.02	≈ $0.006	≈ $0.005

v1.1 확장 버전 (cceb-001 — cceb-030)은 v1.0에서 다루지 않았던 더 어려운 케이스들을 의도적으로 추가했습니다: 대화당 다중 메모리 (architecture + convention 결합), 약속 형태의 모호성 (process vs. technical TODOs), CJK/혼합 언어 대화, 그리고 결정 영향도 대비 후속 TODO 분류 (decision-impact-vs-followup-TODO triage) 등이 포함됩니다. F1 점수는 위 9개 고정 테스트 세트(fixture) 행 대비 12%p(pp) 하락했습니다. 이는 모델의 퇴보(regression)가 아닙니다. 동일한 프롬프트에 대해 v1.0 고정 테스트 세트만 실행했을 때도 여전히 76%의 점수를 기록합니다. 64%라는 수치는 덜 선별된(less cherry-picked) 고정 테스트 분포에서 동일한 추출기(extractor)를 측정한 더 정직한 측정값입니다. 남은 가장 큰 변수는 todo의 정밀도(precision)입니다 (19개의 오탐(false positives) 중 11개가 TODO임). baseline-doc 분석에 따르면, 다음 단계는 추출 후 쌍별 콘텐츠 중복 제거(post-extract pairwise-content dedup) 단계이며, v2.6을 위해 추적 중입니다.

샘플 누락(misses), 샘플 오탐(false positives), 고정 테스트 세트별 세부 사항, v1.0 → v1.1 차이(delta) 분석, 그리고 방법론은 모두 baseline doc에 포함되어 있습니다. 우리는 상위 모델(upstream model)이 업데이트되는 순간 변해버리는 리더보드 점수를 내세우기보다, 교차 검증(cross-examination) 시에도 방어할 수 있는 수치를 공개하고자 합니다.

LongMemEval-50 (교차 코퍼스 건전성 검사, bench/longmemeval/): LongMemEval-S-cleaned의 결정론적인 50개 질문 서브셋에 대해, 우리의 리터럴 토큰 증거 보존(literal-token evidence-preservation) 루브릭을 적용한 결과 gpt-4o-mini는 전체 정답 0 / 50 + 부분 정답 2 / 50의 점수를 기록했습니다.

(약 12분

매 쿼리마다 히스토리를 다시 전송하면 비용이 복리로 증가합니다. 2026-04-01 기준 프런티어 (Frontier) 모델의 입력 가격은 1M 토큰당 약 $1–$3 수준입니다 (Anthropic / OpenAI / Google AI). 도구 호출 (tool-call) 페이로드와 파일 차이점 (file diffs)이 포함되면, 2주간의 Cursor 세션은 안정적으로 100–300K 토큰을 소모합니다. 질문을 던지기도 전에 이를 매 턴마다 붙여넣는 비용은 쿼리당 $0.20–$0.60에 달합니다. 반면, 동일한 대화에서 생성된 AGENTS.md는 1–5K 토큰 규모이며, 세션당 단 한 번만 로드됩니다. 팀 규모와 일일 쿼리 수를 곱해보면, 그 격차는 두 자릿수(two orders of magnitude)에 달합니다.

롱 컨텍스트 (Long-context) 검색은 여전히 핵심 정보가 아닌 데이터에서 성능이 저하됩니다.

# 프로젝트 초기화 (선택 사항: ai-memory를 MCP 서버로 등록)
npx ai-memory-cli init --with-mcp
# 추출 — 내장된 무료 모델로 즉시 작동합니다 (API 키 불필요)
...

임시 디렉터리(tmp dir)에 수동으로 큐레이션된 3개의 메모리 저장소(3-memory store)를 부트스트랩(Bootstrap)하고, 실제 rules --target agents-md 파이프라인을 실행하여 생성된 AGENTS.md를 인라인으로 출력합니다. LLM 호출도, API 키도, 작업 디렉터리의 변경도 없습니다. 설정을 확정하기 전에 "이 도구가 실제로 무엇을 만들어내는가?"라는 질문에 대한 구체적인 답변을 제공합니다.

# 전체 데모 실행, 이후 임시 디렉터리 삭제
npx ai-memory-cli try
# 검사를 위해 임시 시나리오를 디스크에 유지
npx ai-memory-cli try --keep
# 구조화된 출력 (카운트, AGENTS.md 내용, 경로)
npx ai-memory-cli try --json

번들된 시나리오에는 두 명의 작성자에 걸쳐 1개의 결정(PKCE 인증 흐름), 1개의 아키텍처 기록(이벤트 소싱 기반 결제 감사 로그), 1개의 컨벤션(Relay 스타일의 커서 페이지네이션)이 포함되어 있습니다. 오직 컨벤션(Conventions)과 결정(Decisions)만이 AGENTS.md에 기록되며, 이는 실제 rules 명령어가 사용자의 메모리에 적용하는 것과 동일한 필터입니다.

실제 채팅 기록을 대상으로 ai-memory를 설정하기로 결정했다면, try 실행 후에 다음을 실행하세요. 가장 흔한 6가지 설정 문제를 진단하고 각 문제를 정확히 어떻게 해결해야 하는지 알려줍니다.

# 사람이 읽기 쉬운 보고서
npx ai-memory-cli doctor
# 실시간 API 호출 건너뛰기 (오프라인 / CI 환경)
npx ai-memory-cli doctor --no-llm-check
# 자동화 / 버그 보고를 위한 구조화된 출력
npx ai-memory-cli doctor --json

점검 항목은 다음과 같습니다: Node.js 버전, 감지된 에디터 (Cursor / Claude Code / Windsurf / Copilot / Codex CLI + 대화 횟수), LLM 제공업체 + 실시간 연결성 테스트, 메모리 저장소 + 작성자 식별(author resolution), 임베딩(embeddings) 최신성, 그리고 MCP 설정 등록 여부입니다. 모든 검사를 통과하면 종료 코드(Exit code)는 0이며, 검사 중 하나라도 실패하면 1입니다. API 키가 구성되지 않은 경우, doctor는 이제 API 키가 필요 없는 빠른 경로인 try를 안내합니다.

npx ai-memory-cli list # 모든 대화 목록 표시
npx ai-memory-cli list --source cursor # Cursor 대화만 표시
npx ai-memory-cli list --json # JSON 출력

npx ai-memory-cli extract # 모든 대화 추출
npx ai-memory-cli extract --incremental # 새로운 대화만 추출
npx ai-memory-cli extract --pick 3 # 3번 대화만 추출
...

API 키가 없나요? extract는 자동으로 내장된 무료 모델(SiliconFlow를 통한 DeepSeek-V4-Flash)로 폴백(fallback)됩니다. 이 경우 실행당 대화 2개, 대화당 청크(chunk) 20개로 제한됩니다(균등 샘플링(uniform sampling) 방식 — 단순히 대화의 시작 부분만이 아니라 대화 전체의 범위를 포괄합니다). 이 두 가지 제한을 제거하려면 AI_REVIEW_API_KEY 또는 OPENAI_API_KEY를 설정하세요.

extract, summary, 그리고 context --summarize는 대화 발췌본을 설정된 LLM 제공업체로 전송합니다. "로컬 우선(Local-first)" 원칙은 **저장 계층(storage layer)**에 적용됩니다. .ai-memory/는 우리가 절대 업로드하지 않는 일반 마크다운(Markdown) 파일이지만, **추출 호출(extraction call)**은 필연적으로 외부로 나가는 HTTPS 요청입니다. 만약 채팅 기록에 실수로 붙여넣은 API 키, 스택 트레이스(stack traces) 내의 내부 호스트 이름, 또는 로그에 포함된 고객 이메일 주소가 포함되어 있다면, --redact 옵션이 요청이 기기를 떠나기 전에 이를 삭제(scrub)합니다.

$ ai-memory extract --redact
...
Redaction: LLM 전송 전 5개 항목 삭제됨 (118자) — openai-key 3개, 이메일 2개

기본 활성화 규칙(10개): OpenAI / Anthropic / AWS / GitHub / Slack / GCP / Stripe API 키, RFC5322 이메일, 그리고 *.internal / *.corp / *.local / *.lan / *.intra 호스트 이름입니다. 두 가지 선택적 규칙(jwt, aws-secret-key)은 긴 base64 문자열에 대해 오탐(false-positive) 발생률이 높기 때문에 기본적으로 꺼져 있습니다. 이 규칙들은 .ai-memory/.config.json을 통해 활성화할 수 있습니다:

{
"redact": {
"enabled": true,
...

CLI는 설정을 무시(override)합니다: --no-redact는 항상 비활성화하고, --redact는 항상 활성화합니다. 감사 추적(audit trail, 규칙별 히트 횟수)은 삭제(redaction) 기능이 켜져 있을 때 항상 작동하며, 일반 출력과 --json 출력 모두에서 확인할 수 있습니다. 매칭된 값은 절대로 로그에 남기지 않습니다. 그렇게 한다면 삭제의 목적이 무의미해지기 때문입니다.

위협 모델 (Threat model). 심층 방어 (Defense-in-depth)는 적절한 비밀 관리 (Secrets management)를 대체할 수 있는 수단이 아닙니다. 범위 외 항목(이미지 첨부, 기존 메모의 소급 삭제, 구조화된 PII (Personally Identifiable Information) 금고 검사) 및 위협 모델의 경계를 포함한 전체 정책 문서는 docs/redaction-policy-2026-04-26.md에서 확인할 수 있습니다.