agentic-cortex: 코딩 에이전트를 위한 장기 기억 (Long-Term Memory)

요약 (TL;DR): AI 코딩 에이전트는 세션 사이의 모든 것을 잊어버립니다. 3시간 동안 디버깅했던 버그, 아키텍처 결정 사항, Windows 환경에서의 주의사항 등 말이죠. agentic-cortex는 세션과 프로젝트를 가로질러 지속 가능하고, 검색 가능하며, 스스로 개선되는 기억을 에이전트에게 제공합니다. 이 모든 과정은 완전히 로컬에서 이루어지며, API 비용이 전혀 들지 않고, 368개의 테스트를 통과했습니다.

제작 동기

몇 달 전부터 저는 Claude Code, OpenCode, Codebuff를 매일 사용하기 시작했습니다. 모든 세션은 항상 똑같은 방식으로 시작되었습니다. 에이전트에게 제 프로젝트의 컨텍스트를 다시 가르치고, 이미 내린 결정을 다시 설명하며, 지난주에 했던 실수를 똑같이 반복하는 것을 지켜보는 것이었습니다. 채팅 기록 (Chat history)이 도움이 되긴 하지만, 오류의 반복을 방지하거나 아키텍처 선택 뒤에 숨겨진 '이유 (why)'를 인코딩(encode)해주지는 못합니다.

저는 에이전트가 단순히 대화를 기억하는 것을 넘어, 시간이 지남에 따라 개선되고 프로젝트 간에 전이될 수 있는 실제 지식 베이스 (knowledge base)를 구축하기를 원했습니다. 그래서 agentic-cortex를 만들었습니다.

주요 기능

핵심 기억 엔진 (Core Memory Engine)

• 13가지 유형의 기억 (typed memories): 지시 (instruction), 사실 (fact), 결정 (decision), 목표 (goal), 약속 (commitment), 선호도 (preference), 관계 (relationship), 컨텍스트 (context), 이벤트 (event), 학습 (learning), 관찰 (observation), 결과물 (artifact), 오류 (error)
• 신뢰도 점수 (Confidence scoring) (0–100) + 출처 추적 (provenance tracking) (명시적, 추론됨, 관찰됨)
• BGE 768차원 임베딩 (embeddings) 및 FTS5+시맨틱 검색 (semantic search)과 크로스 인코더 리랭킹 (cross-encoder reranking)을 결합한 하이브리드 검색
• 저장 시 중복 제거 (Save-time deduplication): 코사인 유사도 (cosine similarity) ≥ 0.97 → 중복 생성 대신 기존 기억을 강화
• 시간 기반 쿼리 (Temporal queries): --changed-since, --as-of 날짜 필터

인자 없는 부트스트랩 (Zero-Arg Bootstrap)

agentic-cortex bootstrap

인자가 필요 없습니다. git 브랜치, 세션 프롬프트(prompt) 또는 최근 활동으로부터 작업을 추론합니다. 실행 가능한 통찰(actionable insights), 계층화된 관련 기억, 최근 세션, 오래된 기억에 대한 경고, 요약된 코딩 표준, 코드베이스 그래프, 그리고 머신 전체의 글로벌 볼트 (global vault)를 포함한 구조화된 XML을 단 한 번의 호출로 반환합니다. 활성화된 세션이 없다면 세션을 자동으로 시작합니다.

자동 유형 감지 (Auto Type Detection)

콘텐츠를 패턴 매칭하여 error, decision, learning, preference, fact, instruction, event 또는 goal로 분류합니다. 사용자가 직접 덮어쓰고 싶은 경우가 아니라면 --type 플래그를 사용할 필요가 없습니다.

agentic-cortex save "TypeError: Cannot read properties of undefined (reading 'map')"
# → type: error로 자동 감지됨, confidence: 95

머신 전체 글로벌 볼트 (Machine-Wide Global Vault)

Project A에서 얻은 학습 내용이 Project B, C, D의 에이전트들을 자동으로 보호합니다. 이를 프로젝트 간 면역 체계(cross-project immune system)라고 생각하면 됩니다.

• 자동 승격 (Auto-promotion): 상대적 임계값(상위 20% 신뢰도, 중앙값 유용성의 2배)을 사용하여 수행되며, 프로젝트가 성장함에 따라 스스로 튜닝됩니다.
• 수동 승격 (Manual promotion): agentic-cortex promote-global <id>
• 프로젝트 간 검색 (Cross-project search): agentic-cortex machine-search "query"
• 분석 (Analytics): agentic-cortex machine-memory --analytics

자기 개선 루프 (Self-Improving Loop)

• 오류 근본 원인 분석 (Error RCA): 오류를 감지하고 LLM 근본 원인 분석 (root cause analysis)을 통해 체계적인 학습 내용을 생성합니다.
• 충돌 감지 (Conflict detection): 의미론적 유사성 (semantic similarity)과 LLM 해결 (resolution)을 사용하여 모순을 찾아냅니다.
• 증거 기반 신뢰도 (Evidence-based confidence): 의도(intent) → 행동(action) → 결과(outcome)의 삼중항 (triplets)을 추적하고 그에 따라 점수를 조정합니다.
• 최신성 점수 (Freshness scoring, 0–100): 액세스 최신성, 신뢰도, 유용성을 결합하여 오래된 기억을 자동으로 아카이브합니다.
• 자동 유지 관리 스케줄러 (Auto-maintenance scheduler): 약 50회의 저장(save)마다 실행되며, 사이클 사이의 최소 간격은 6시간입니다.

코드베이스 그래프 (Codebase Graph)

결정론적 정적 분석 (Deterministic static analysis)을 수행하며, LLM 비용이 전혀 들지 않고 SHA-256으로 캐싱됩니다. 파일, export, import, 함수 시그니처 (function signatures), API 경로 (API routes), Prisma 스키마 (Prisma schemas), 아키텍처 계층 (UI/API/Service/Data), 패러다임 및 기술 스택을 추출합니다. LLM 토큰 효율성에 최적화된 구조화된 XML을 출력하며, 이는 동일한 마크다운 (markdown)보다 토큰을 약 4배 적게 사용합니다. git checkout, merge, pull, commit 시 후크 (hooks)를 통해 자동으로 주입됩니다.

에이전트 최적화 출력 (Agent-Optimized Output)

• knowledge.md는 XML 구조로 되어 있으며, LLM (Large Language Model) 소비에 최적화된 토큰 구조를 가집니다.
• Claude Code, Cursor, OpenCode를 위한 탐색(Discovery) 파일이 자동으로 생성됩니다.
• stdio JSON-RPC를 통해 39개 이상의 도구를 제공하는 MCP (Model Context Protocol) 서버 — 설정이 필요 없으며 HTTP 포트를 사용하지 않습니다.
• 사전 로드된 코딩 표준 (DRY, KISS, SOLID, Clean Code, Karpathy) — 항상 주입됩니다.

추가 지능 (Additional Intelligence)

• 근거 기반 QA (Grounded QA): 관련 메모리를 검색하여 출처 인용과 함께 LLM 답변을 제공합니다.
• 트랜스크립트 수집 (Transcript ingestion): 정규 표현식 (regex)과 LLM을 사용하여 대화에서 결정 사항, 오류 및 학습 내용을 추출합니다.
• 기술/절차 추출 (Skill/procedure extraction): 구조화된 필드 (트리거, 전제 조건, 단계, 사후 조건)를 사용하여 추출합니다.
• 일일 요약 (Daily summaries): LLM 및 템플릿 폴백 (fallback)을 사용합니다.
• Obsidian 내보내기 (Obsidian export): 위키링크 (wikilinks) 및 태그 인덱스를 포함하여 내보냅니다.
• 파일 감시 데몬 (File watcher daemon): 자동 캡처를 위해 작동합니다.
• HTTP API 서버: 37777 포트에서 작동합니다.

기능 비교 (Feature Comparison)

기능	agentic-cortex	LangChain Memory	ChromaDB / Pinecone	Mem0	Cursor Rules
유형화된 메모리 카테고리 (Typed memory categories)	13	1 (메시지)	0 (원시 벡터)	~6	0 (정적 텍스트)
...

핵심 차별점 (Key Differentiators)

vs. LangChain Memory: LangChain은 메시지 버퍼를 제공합니다. agentic-cortex는 전체 지식 라이프사이클을 제공합니다 — 신뢰도 감쇠 (confidence decay)가 적용된 유형화된 메모리, 자동 오류-학습 파이프라인, 프로젝트 간 지식 전송, 그리고 설정 없이 실행되는 자기 개선 루프 (self-improving loop)를 포함합니다.

vs. 벡터 DB (ChromaDB, Pinecone): 벡터 데이터베이스는 임베딩 (embeddings)을 저장합니다. agentic-cortex는 '지식'을 저장합니다 — 유형화되고, 점수가 매겨지며, 버전 관리되고, 상호 참조되며, 스스로 개선되는 지식입니다. 벡터 DB가 구성 요소(building block)라면, agentic-cortex는 완성된 집입니다.

vs. Mem0: agentic-cortex는 작업 추론을 통한 인자 없는 부트스트랩 (zero-arg bootstrap), 자기 조정 승격 (self-tuning promotion) 기능이 있는 머신 전역 글로벌 볼트 (global vault), 결정론적 코드베이스 그래프 생성, 의미론적+LLM을 통한 충돌 탐지, 자동 아카이빙을 포함한 최신성 점수 산정, 그리고 13가지 메모리 유형 (Mem0의 약 6가지 광범위한 카테고리 대비)을 추가로 제공합니다.

vs. Cursor Rules / 수동 컨텍스트 파일 (Manual Context Files): 정적인 .cursorrules 파일은 적응하지 못합니다. agentic-cortex는 시맨틱 검색 (semantic search), 시간에 따른 신뢰도 감쇠 (confidence decay), 프로젝트 간 전이 (cross-project transfer), 증거 기반 유용성 점수 산정 (evidence-based utility scoring), 그리고 자기 개선형 RCA 루프 (self-improving RCA loop)를 통해 메모리를 자동으로 영구 저장합니다. 사용자는 더 이상 컨텍스트 파일을 유지 관리할 필요가 없으며, 에이전트가 스스로 지식을 구축하기 시작합니다.

스택 (The Stack)

Node.js · SQLite (기기당 단일 DB) · Xenova BGE 임베딩 (embeddings, 전적으로 로컬 실행) · 하이브리드 FTS5+시맨틱 검색 (semantic search) · 교차 인코더 재순위화 (Cross-encoder reranking) · LLM 요약을 위한 선택적 llama.cpp

시작하기

npm install -g agentic-cortex
agentic-cortex bootstrap

368개의 테스트 통과. MIT 라이선스. 무료이며 완전한 오픈 소스입니다.

• GitHub: github.com/zallauddin/agentic-cortex
• npm: npmjs.com/package/agentic-cortex

만약 당신의 에이전트들이 매 세션마다 동일한 솔루션을 계속해서 재발명하고 있다면, 프로젝트 전반에 걸쳐 지속되고, 스스로 개선하며, 보호되는 메모리 시스템을 부여하세요.