agentmemory
— AI 코딩 에이전트의 영속 기억, 내부 구현까지 뜯어보기

rohitg00/agentmemory — "쓰면 이렇게 됩니다"가 아니라 hooks.json · hybrid-search.ts · local.ts를 직접 읽고 "이런 코드라서 그 결과가 나옵니다"를 확인

출처: github.com/rohitg00/agentmemory — README, Apache-2.0

AI 에이전트는 세션마다 기억을 잃는다

"저번에 말했잖아요, 이 프로젝트는 TypeScript strict 쓰고
테스트는 vitest야." → 에이전트: "안녕하세요, 뭘 도와드릴까요?"

Claude Code, Cursor, Cline 등 모든 코딩 에이전트의 공통 고통 — 컨텍스트는 세션과 함께 증발한다.

출처: github.com/rohitg00/agentmemory — README "The Problem" 섹션

CLAUDE.md에 수동으로 메모? — 한계가 있다

가장 흔한 해결책: CLAUDE.md에 프로젝트 규칙을 적어두기. 실제로 많이 쓰이고, 없는 것보다 훨씬 낫다. 하지만:

출처: github.com/rohitg00/agentmemory — README 비교 섹션; 직접 분석

자동 캡처 → 압축 → 세션 시작 주입

agentmemory의 핵심 루프 세 단계. 사람이 아무것도 하지 않아도 돌아간다.

지원 환경: Claude Code (플러그인), Cursor · Gemini CLI · Cline · Goose (MCP 서버 설정), 그 외 모든 에이전트 (REST API, 주장: 128 endpoints on port 3111).

출처: github.com/rohitg00/agentmemory — README, package.json

로컬 SQLite + iii-engine — 외부 DB 불필요

agentmemory는 클라우드나 외부 벡터 DB를 쓰지 않는다. 모든 데이터는 로컬 SQLite와 자체 인덱스 엔진(iii-engine)에 저장된다.

출처: src/state/hybrid-search.ts · src/mcp/tools-registry.ts

BM25 + Vector + Graph, RRF로 융합 — 실제 코드

단순 키워드 검색도, 단순 벡터 검색도 아니다. 세 신호를 동시에 내고 RRF(Reciprocal Rank Fusion)로 합친다.

// src/state/hybrid-search.ts (검증된 실제 코드)
const RRF_K = 60;

export class HybridSearch {
  constructor(
    private bm25: SearchIndex,
    private vector: VectorIndex | null,
    private embeddingProvider: EmbeddingProvider | null,
    private kv: StateKV,
    private bm25Weight = 0.4,
    private vectorWeight = 0.6,
    private graphWeight = 0.3,
    private rerankEnabled = process.env.RERANK_ENABLED === "true",
  ) { ... }

  // RRF 점수 계산 (combinedScore)
  combinedScore:
    effectiveBm25W  * (1 / (RRF_K + bm25Rank)) +
    effectiveVectorW * (1 / (RRF_K + vectorRank)) +
    effectiveGraphW  * (1 / (RRF_K + graphRank)),
}

핵심: 각 검색 결과의 순위(rank)를 RRF_K+rank로 나눠 역수를 취한 뒤 가중합. 순위가 높을수록(=1에 가까울수록) 기여도 높음. RRF_K=60은 상위 순위 간 점수 차이를 완만하게 만드는 상수.

출처: src/state/hybrid-search.ts — 직접 읽어 검증한 실제 코드

기본값: LLM 호출 없음 — 임베딩도 로컬 384차원

이 주제가 스터디 기준(추가 과금 없음)을 통과한 이유. 기본 설정에서 외부 API 호출이 전혀 없다.

// src/providers/embedding/local.ts (검증된 실제 코드)
export class LocalEmbeddingProvider implements EmbeddingProvider {
  readonly name = "local";
  readonly dimensions = 384;
  private extractor: Awaited<ReturnType<Pipeline>> | null = null;

  async embedBatch(texts: string[]): Promise<Float32Array[]> {
    const extractor = await this.getExtractor();
    const output = await extractor(texts, { pooling: "mean", normalize: true });
    return vectors.map((v: number[]) => new Float32Array(v));
  }

  private async getExtractor() {
    // @ts-ignore - optional peer dependency
    transformers = await import("@xenova/transformers");
    return transformers.pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2");
  }
}

모델: all-MiniLM-L6-v2 (Xenova/Transformers.js 포팅) — 384차원, 평균 풀링 + 정규화. Node.js에서 로컬 실행, 인터넷 연결 불필요.

출처: src/providers/embedding/local.ts — 직접 읽어 검증

hooks.json — 에이전트 활동이 자동으로 기록되는 이유

"사용자가 아무것도 안 해도" 캡처되는 핵심: Claude Code의 hooks 시스템에 node 스크립트를 등록해 에이전트의 모든 도구 사용에 끼어들어 기록한다.

// plugin/hooks/hooks.json (검증된 실제 파일 전체 구조)
{
  "hooks": {
    "SessionStart":    [{ "command": "node .../session-start.mjs" }],
    "UserPromptSubmit":[{ "command": "node .../prompt-submit.mjs" }],
    "PreToolUse":      [{ "matcher": "Edit|Write|Read|Glob|Grep",
                          "command": "node .../pre-tool-use.mjs" }],
    "PostToolUse":     [{ "command": "node .../post-tool-use.mjs" }],
    "PostToolUseFailure":[{ "command": "node .../post-tool-failure.mjs" }],
    "PreCompact":      [{ "command": "node .../pre-compact.mjs" }],
    "SubagentStart":   [{ "command": "node .../subagent-start.mjs" }],
    "SubagentStop":    [{ "command": "node .../subagent-stop.mjs" }],
    "Stop":            [{ "command": "node .../stop.mjs" }],
    "SessionEnd":      [{ "command": "node .../session-end.mjs" }]
  }
}

핵심 훅 세 가지: SessionStart = 관련 기억 주입, PostToolUse = 툴 결과 캡처, PreCompact = 압축 전 중요 내용 저장.

출처: plugin/hooks/hooks.json — 직접 읽어 검증

좋은 점과 한계 — 솔직하게

출처: github.com/rohitg00/agentmemory — 소스 직접 분석 기반 평가

agentmemory가 푼 것과 그 방법

AI 에이전트의 기억은
코드 한 줄 없이 hooks 설정만으로 자동화할 수 있다.

출처: github.com/rohitg00/agentmemory — 소스 직접 검증 (2026-06)

감사합니다

질문 / 각자의 "에이전트에게 또 설명한 경험" 공유

참고 자료

• rohitg00/agentmemory — 공식 레포 (Apache-2.0)
• src/state/hybrid-search.ts — RRF_K=60, 가중치, tripleStreamSearch 구현
• src/providers/embedding/local.ts — LocalEmbeddingProvider, 384차원, all-MiniLM-L6-v2
• plugin/hooks/hooks.json — Claude Code hooks 설정 전체
• src/mcp/tools-registry.ts — MCP tool 정의 (~56개)

출처: 위 모든 링크 — 직접 소스 분석 (2026-06-16 기준)