서론 (Introduction)

"AI 에이전트가 망각하는 이유는 모델이 고장 나서가 아니라, 무언가를 적어둘 장소를 아무도 주지 않았기 때문입니다."

이 글은 "하루에 하나의 오픈 소스 프로젝트 (One Open Source Project a Day)" 시리즈의 140번째 기사입니다. 오늘의 프로젝트는 OptMem입니다. 이는 HigherOrderCO의 설립자인 Victor Taelin이 만든 AI 에이전트를 위한 최소한의 지속적 메모리 (persistent memory) 시스템입니다. 핵심 설계는 **하나의 Python 스크립트 + 하나의 426토큰 프롬프트 (prompt)**로 구성되어 있어, AI 에이전트가 지난 세션에서 일어난 일을 기억할 수 있게 합니다.

Claude Code, Codex, Cursor — 이 도구들은 공통된 한계를 공유합니다. 각 새로운 세션은 제로(zero) 상태에서 시작됩니다. 아키텍처 결정 사항, 발견된 함정들, 지난 세션에서 기억된 선호도 등이 모두 사라집니다. 문맥 (context)을 반복해서 다시 설명해야 하며, 때로는 같은 문제에 두 번 빠지기도 합니다. OptMem은 이를 직접적으로 해결합니다. 에이전트에게 지속적이고 로컬인 메모리 저장소를 제공하여, 실제로 기억할 수 있게 합니다.

전체 솔루션의 복잡도는 매우 낮습니다: 의존성 없는 (zero-dependency) Python 스크립트 하나와, 여러분의 AGENTS.md 파일에 프롬프트 블록 하나를 붙여넣는 것이 전부입니다.

별 1,100개. Victor Taelin의 개인 프로젝트입니다.

학습 내용 (What You'll Learn)

• AI 에이전트에게 왜 세션 간 메모리가 없는지, 그리고 OptMem이 이를 어떻게 해결하는지
• 이진 트리 요약 (Binary tree summarization): 토큰 소모를 제어하면서 O(1) 조회를 수행하는 방법
• memo wake / memo note / memo nap: 6개의 모든 명령어가 작동하는 방식
• 426토큰 프롬프트 블록이 실제로 무엇을 담고 있는지, 그리고 왜 하필 426토큰인지
• OptMem과 벡터 데이터베이스 (vector database)의 실제 차이점, 그리고 각각 어떤 규모에 적합한지
• Claude Code를 위한 전체 설정 가이드

사전 요구 사항 (Prerequisites)

• Claude Code 또는 유사한 AI 코딩 도구 사용 경험
• AGENTS.md / CLAUDE.md 개념에 대한 익숙함
• 기본적인 Python 환경 사용 능력

문제점: AI 에이전트는 메모리가 없다 (The Problem: AI Agents Have No Memory)

프로젝트에서 Claude Code와 진행하는 세션에서는 다음과 같은 것들이 발생할 수 있습니다:

• 비밀번호 대신 매직 링크 (magic links)를 사용하기로 한 결정
• 특정 API에 대한 속도 제한 (rate limit) 발견
• 개발용 데이터베이스 연결 문자열 (connection string)

세션이 종료됩니다. 다음에 Claude Code를 열 때, 그 어떤 것도 유지되지 않습니다. 문맥을 다시 설명하고, 배경 지식을 다시 공유하며, 때로는 동일한 문제에 다시 부딪히기도 합니다.

이 문제에 대한 일반적인 접근 방식:

OptMem의 접근 방식: 인간의 유지보수에 의존하는 대신, 에이전트가 자신의 메모리를 직접 소유하게 합니다. 에이전트는 세션 시작 시 이전 메모리를 로드하고, 작업하면서 보관할 가치가 있는 정보를 기록하며, 해당 메모리는 세션 간에 로컬에 지속적으로 유지됩니다.

핵심 아키텍처: 추가 전용 로그 (Append-Only Log) + 이진 트리 요약 (Binary Tree Summaries)

OptMem은 모든 것을 ~/.optmem/memory/ 아래에 저장합니다:

~/.optmem/memory/
├── LOG.txt      ← 모든 원시 메모리, 한 줄당 하나, 추가 전용 (append-only), 수정 불가
├── TREE/        ← 이진 트리 요약 노드 (캐시, LOG.txt로부터 재구축 가능)
...

LOG.txt: 불변의 사실 (Immutable Facts)

모든 memo note "something" 명령은 LOG.txt에 한 줄을 추가합니다. 이 파일은 수정되거나 삭제되지 않으며, 오직 추가만 됩니다. 고정 너비 레코드 형식 (Fixed-width record format)을 사용하므로 각 메모리의 **위치(position)가 곧 정체성(identity)**이 되며, 이를 통해 전체 텍스트 스캔이 아닌 O(1) 탐색으로 조회가 가능합니다.

0000000001 | 2026-08-03T10:23:11 | 인증 흐름은 매직 링크를 사용하며, 비밀번호는 없음
0000000002 | 2026-08-03T10:45:33 | stripe API 속도 제한 (rate limit)은 키당 분당 100회 요청임
0000000003 | 2026-08-03T11:02:55 | localhost:5432의 postgres, db=dev_app
...

TREE/: 이진 트리 요약 (Binary Tree Summaries) (캐시)

메모리가 축적됨에 따라, 에이전트가 깨어날 때마다 모든 원시 메모리를 보여주는 것은 토큰 예산 (token budgets)을 빠르게 소모할 것입니다. OptMem의 해결책은 요약된 이진 트리입니다.

원시 메모리:                 트리 구조:

#0: 매직 링크               #0-3 (4개의 요약)
...

• 메모리 #0과 #1이 노드 #0-1로 병합됩니다 (두 개의 메모리 요약)
• 노드 #0-1과 #2-3이 #0-3으로 병합됩니다 (네 개의 메모리 요약)
• 트리 상단으로 올라가며 이 과정이 계속됩니다.

핵심 불변량 (The key invariant): TREE/에 있는 모든 것은 **캐시 (cache)**이며, LOG.txt로부터 완전히 재구축 가능합니다. LOG.txt가 유일한 진실의 원천 (source of truth)입니다.

wake가 로드하는 것

memo wake는 트리를 읽고 계층화된 뷰 (layered view)를 출력합니다:

## Memory

[#0-1023] 요약: 인증에는 매직 링크 (magic links)를 사용함. Stripe 속도는 분당 100회. DB는 localhost:5432에 위치...
...

**최근 메모리 (Recent memories)**는 있는 그대로 (정확하게) 나타납니다. **오래된 메모리 (Older memories)**는 점진적으로 더 거친 요약 (압축됨) 형태로 나타납니다. WAKE_LINES는 로드할 라인 수를 제어하며, 기본값인 96라인은 약 8k 토큰의 비용이 발생합니다.

6가지 명령어

memo wake

세션 시작 시 실행합니다. 메모리 트리를 로드하고, 에이전트가 읽을 수 있도록 ## Memory 블록을 출력합니다.

memo wake
# 출력: 컨텍스트에 주입되는 계층화된 메모리 요약

memo note "..."

사실을 기록합니다. 최대 280바이트까지 가능합니다 (Twitter 스타일로, 메모리를 원자적 (atomic)으로 유지함).

memo note "Postgres가 너무 느린 것을 테스트한 후 세션 저장소로 Redis를 사용하기로 결정함"

memo nap

대기 중인 병합 요청을 처리합니다. 이진 트리 노드 (binary tree nodes)를 병합하기 위해 LLM 기반의 요약 (summarization)을 실행합니다. 별도의 백그라운드 프로세스가 존재하지 않으므로, 압축은 에이전트의 작업 중에 인라인 (inline)으로 수행됩니다.

memo recall <regex>

모든 메모리에 대해 전체 텍스트 정규 표현식 (regex) 검색을 수행합니다.

memo recall "redis|session"
# redis 또는 session을 언급하는 모든 메모리 검색

memo zoom <lo>-<hi>

요약 노드를 두 개의 자식 노드로 확장하며, 원시 메모리 (raw memories)까지 재귀적으로 내려갑니다.

memo zoom 0-1023
# [0-511] 요약 및 [512-1023] 요약으로 확장
memo zoom 0-511
...

memo forget <lo>-<hi>

품질이 낮은 요약 노드를 삭제합니다. 다음 nap 실행 시 원시 메모리로부터 해당 노드를 재구축합니다.

426토큰 프롬프트 블록

OptMem 통합의 전체 내용은 AGENTS.md 또는 CLAUDE.md에 붙여넣는 다음 블록입니다:

## Memory

당신은 ~/.optmem/memo에 있는 `memo` 명령어를 통해 지속적인 메모리를 가집니다.
...

이 프롬프트는 네 가지 사항을 처리합니다:

1. 강제된 순서 (Enforced ordering): wake가 다른 모든 작업보다 먼저 실행됩니다.
2. 트리거 기준 (Trigger criteria): 무엇을 기록할지에 대한 명시적인 가이드 — 결정 사항, 발견, 선호도, 함정(pitfalls)
3. 하위 에이전트 보호 (Subagent protection): 병렬로 실행되는 하위 에이전트들은 메모를 실행하지 않으며, 이를 통해 동시 쓰기로 인한 데이터 손상을 방지합니다.
4. 불변성 제약 (Immutability constraint): 에이전트는 오직 명령어를 통해서만 작동하며, 메모리 파일에 직접 접근하지 않습니다.

설치 및 설정 (Installation and Setup)

설치 (단일 명령어) (Install (One Command))

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/VictorTaelin/OptMem/main/install.sh | bash

...

설치 후, memo 명령어를 PATH에서 사용할 수 있으며 ~/.optmem/ 디렉토리가 생성됩니다.

Claude Code와 통합 (Integrate with Claude Code)

# 1. 프롬프트 블록을 가져오기 위해 memo wake 실행
memo wake

...

메모리 디렉토리 설정 (Configure Memory Directory)

# 기기 간 동기화를 위해 Dropbox / iCloud / git 리포지토리에 메모리 저장
export MEMORY_DIR=~/Dropbox/optmem-memory

OptMem vs 벡터 데이터베이스 (OptMem vs Vector Databases)

OptMem의 핵심 장점: 투명성(transparency). LOG.txt를 열어 에이전트가 기록한 모든 줄을 읽고, 이를 신뢰할지 결정할 수 있습니다. 벡터 데이터베이스는 사람이 읽을 수 없는 부동 소수점(floats)을 저장합니다.

OptMem의 검색 한계: 정규 표현식(regex)은 정확한 단어 일치를 요구합니다. 만약 메모에 "로그인이 매직 링크로 전환됨"이라고 적혀 있는데 나중에 "인증 방식이 뭐야?"라고 묻는다면, 정규 표현식은 이를 찾아내지 못합니다. 이진 트리 요약(binary tree summaries)이 이를 부분적으로 보완합니다. 즉, wake가 요약을 컨텍스트(context)에 로드하면 모델이 의미론적 매칭(semantic matching)을 수행합니다. 하지만 모든 세션은 실제 필요한 과거 메모의 양과 관계없이 고정된 토큰 예산(token budget)을 소비합니다.

적합한 범위 (The right scope): 한 명의 사용자, 한 대의 기기, 지난 화요일의 결정 사항을 기억해야 하는 하나의 프로젝트용 AI 에이전트. 에이전트가 기록한 내용을 감사(audit)하기 위해 텍스트 파일을 열 수 있고, 검색 정밀도보다 제어 가능성(controllability)을 우선시하는 경우에 적합합니다.

프로젝트 리소스 (Project Resources)

• 🌟 GitHub: VictorTaelin/OptMem
• 👤 Author: Victor Taelin (HigherOrderCO 설립자; Bend 언어 및 HVM 런타임 개발자)

요약 (Summary)

OptMem은 "충분히 괜찮은(good enough)" 엔지니어링 관점을 보여줍니다. 즉, 하나의 실제적인 문제를 해결하되 과도한 엔지니어링(over-engineering)은 건너뜁니다.

AI 에이전트를 위한 세션 간 메모리(Cross-session memory)는 실제로 매일 발생하는 고충입니다. 벡터 데이터베이스 (Vector databases), RAG 파이프라인, 임베딩 모델 (embedding models) 등은 기술적으로는 더 완벽할지 모르지만, 개인 개발자에게 설정 오버헤드(setup overhead)는 실질적인 부담입니다. OptMem의 해답은 다음과 같습니다: 하나의 Python 스크립트, 의존성 제로 (zero dependencies), 추가 전용 파일 (append-only files), 이진 트리 압축 (binary tree compression), 그리고 프롬프트 하나만 붙여넣으면 통합 완료.

이 아키텍처는 한 가지를 제대로 짚었습니다: LOG.txt가 유일한 진실의 원천 (source of truth)이며, TREE/는 단순한 캐시 (cache)일 뿐이라는 점입니다. 요약(summarization) 성능이 어떻게 나오든 상관없이, 원본 메모리는 온전하게 보존되며 언제든 재구축될 수 있습니다. 최악의 경우에도 "조금 느려질" 뿐, "데이터 손실"이 발생하지는 않습니다.

만약 Claude Code를 매일 사용한다면, OptMem은 구체적이고 반복되는 고충을 해결해 줍니다. 일단 설치하면 백그라운드에서 조용히 실행됩니다. 사용자는 에이전트가 중요한 결정을 실제로 기록했는지 가끔 확인하기만 하면 됩니다.

엄선된 AI 에이전트와 기술을 위한 마켓플레이스인 PrimeSkills를 탐색해 보세요. 각 기술은 실제 기업 워크플로우에서 검증되었으며, 과장된 광고를 걷어내고 진정으로 작동하는 것들만 남겼습니다.

더 유용한 통찰과 흥미로운 제품들을 확인하시려면 저의 홈페이지를 방문해 주세요.