LedgerMind 3.0 3.3.2: 우리가 ‘It Works’를 ‘It Works Brilliantly’로 바꾼 방법

I’m happy to translate the article for you, but I’ll need the full text you’d like translated. Please paste the content (excluding the source line you’ve already provided), and I’ll return a Korean version while preserving the original formatting, markdown, and any code blocks or URLs.

스포일러: 497개의 커밋, SQLite와 함께한 세 번의 불면의 밤, 그리고 죽지 않으려는 아주 고집 센 레이스 컨디션

읽는 시간: ~12 분 · 대상: AI‑에이전트 개발자, 아키텍처‑드라마 애호가

마지막 몇 달간 LedgerMind의 이야기를 놓쳤다면, 간단히 정리하면: 버전 3.0에서 단순히 동작하던 시스템을 빠르고, 안정적으로, 그리고 인공지능 요소가 포함된 시스템으로 바꿨습니다.

마케팅 과장처럼 들리나요? 이해합니다. 그럼 바로 사실로 들어가 보죠.

지표

하지만 처음부터 시작합시다. 이 숫자들 뒤에는 실제 엔지니어링 드라마가 숨어 있습니다.

The Problem: A Classic TOCTOU Race

두 에이전트가 동시에 같은 대상에 대한 결정을 쓰기로 합니다.

1. First agent가 확인 – 충돌 없음.
2. Second agent가 확인 – 충돌 없음.
3. First agent가 기록.
4. Second agent가 기록.

Boom. 메타데이터가 손상되었습니다.

“이런 일은 거의 일어나지 않아요,” 라고 누군가 말했습니다.
“거의가 절대는 아니다,” 라고 CI/CD가 새벽 3시에 답했습니다.

Fix

• BEGIN IMMEDIATE를 사용한 실제 ACID 트랜잭션
• 전역 잠금 레지스트리
• 10 분 후 자동 오래된 잠금 정리

이제 하나의 프로젝트에 에이전트 열 개를 실행해도 문제를 스스로 해결합니다.

Source: …

SQLite & Concurrency

SQLite는 훌륭합니다—하지만 백그라운드 워커와 사용자 요청이 동시에 쓰기를 시도하면 상황이… 그다지 훌륭하지 않게 됩니다.

sqlite3.OperationalError: database is locked

우리가 시도했지만 (실패한) 방법

• ❌ 타임아웃 증가 (도움 안 됨)
• ❌ 재시도 로직 추가 (도움은 되었지만 해킹 같은 느낌)
• ❌ 데이터베이스 신에게 기도 (효과 없음)

결국 성공한 방법

• 제안당 트랜잭션으로 인핸스먼트 배치를 나누기
• worker.pid를 사용해 멈춘 워커 감지하기
• 자동 오래된 락 정리

결과: 백그라운드 워커가 이제 5분마다 실행되며, 사용자는 그 존재조차 눈치채지 못합니다. 마땅히 그래야 하죠.

Knowledge Lifecycle: PATTERN → EMERGENT → CANONICAL

LifecycleEngine는 전환을 자동으로 관리합니다. 사용자는 아무 것도 할 필요가 없으며, 시스템이 지식이 “성숙”했을 때를 판단합니다.

왜? 한 달 동안 운영하면 수백 개의 결정을 축적하게 됩니다. 검색에서 현재의 결정만 보고 싶고, 첫 날에 적고 잊어버린 결정은 보고 싶지 않습니다.

v3.3의 가장 좋아하는 기능

이전: 결정을 기록하면 시스템이 저장합니다.

이후: 시스템이 당신의 결정 시퀀스를 분석하고 사고 패턴을 식별합니다.

# You just record decisions
memory.record_decision("Use PostgreSQL", target="db")
memory.record_decision("Add JSONB",       target="db")
memory.record_decision("Migrations via Alembic", target="db")

# The system notices the pattern:
# "When user builds API → PostgreSQL + JSONB + Alembic"
# And next time will suggest this stack automatically

이것은 마법이 아닙니다. Trajectory‑based Reflection Engine은 당신의 결정을 그래프로 구축하고 그 안에서 반복되는 경로를 찾아냅니다.

통합 및 자동화 수준

실제로 이것은 무엇을 의미합니까?
LedgerMind에 대해 전혀 생각하지 않아도 됩니다. 그냥 작동합니다.

• 모든 LLM 요청 전에, 시스템이 메모리에서 컨텍스트를 주입합니다.
• 모든 응답 후 – 결과를 자동으로 기록합니다.

당신은 평소처럼 작업합니다. 시스템이 당신을 위해 작동합니다.

검색 속도 저하 및 해결

v3.3 개발 초기에 검색 속도가 ~4 000 OPS에서 ~2 000 OPS로 느려지는 현상을 발견했습니다.

• 원인: 이벤트와 의사결정 사이 연결을 검증하기 위해 linked_id 검증을 추가했습니다. 이로 인해 모든 검색이 전체 테이블 스캔을 수행했습니다.
• 해결책:
  • linked_id에 인덱스 추가
  • 간단한 쿼리를 위한 Fast‑path 휴리스틱 적용
  • 메타데이터 배치 처리

-- Before: slow JOIN without index
SELECT * FROM decisions WHERE linked_id IN (...);

-- After: fast lookup by index
CREATE INDEX idx_linked_id ON episodic_events(linked_id);

결과:

• 의미 검색에서 5 500+ OPS 달성
• 키워드 전용 검색에서 14 000+ OPS 달성

쓰기 경로: 결정을 기록할 때 무슨 일이 일어나나요?

1. SQLite WAL 쓰기
2. 암호학적 감사를 위한 Git 커밋
3. 벡터 임베딩 생성
4. 링크 카운트 업데이트

이 모든 작업은 초당 8 연산에 들어갑니다. 비교를 위해, v3.0은 약 2 OPS를 처리했습니다.

어떻게?

• 지연된 VectorStore 로딩
• 트랜잭션을 제안으로 분할
• 경로 검증 캐싱

모바일 지원 (Termux)

LedgerMind는 이제 Termux를 통해 Android에서 실행되며, 4‑bit 양자화 모델을 사용합니다.

왜? 때때로 이동 중에 프로토타입을 만들 필요가 있기 때문입니다. 그리고 우리가 할 수 있기 때문이죠.

버그 수정 및 개선

아키텍처 리팩터링

Before: 하나의 거대한 Memory 클래스 (~2 000 줄).

After: 아홉 개의 전문화된 서비스:

Memory (coordinator)
├── EpisodicStore   # short‑term events
├── SemanticStore   # long‑term knowledge
├── VectorStore     # embeddings
├── LockRegistry    # global lock handling
├── TransactionMgr  # ACID transaction orchestration
├── LifecycleEngine # knowledge phase transitions
├── SearchEngine    # fast‑path & semantic search
├── AuditLog        # Git‑based cryptographic audit
└── WorkerPool      # background enrichment workers

TL;DR

• +175 % 검색 처리량, ‑97 % 쓰기 지연시간.
• 497 커밋, 프로덕션에서 0 치명적인 버그.
• 실제 ACID 트랜잭션, 전역 락 레지스트리, 오래된 락 정리.
• 지식이 이제 자동으로 진화 (PATTERN → EMERGENT → CANONICAL).
• 풀‑스택 통합 (VS Code, Claude Code, Cursor, Gemini CLI).
• Termux를 통한 모바일 지원.

그것이 LedgerMind가 “작동한다”에서 “빠르고, 신뢰할 수 있으며, 지능적으로 작동한다”는 이야기가 됩니다. 🚀

decisions + Git

├── VectorStore      # embeddings
├── ConflictEngine   # conflict detection
├── ResolutionEngine # supersede validation
├── DecayEngine      # pruning old data
├── ReflectionEngine # pattern discovery
└── LifecycleEngine  # phase management

왜?
각 컴포넌트를 독립적으로 테스트하고, 최적화하며, 교체할 수 있습니다. 6개월 뒤에 새로운 개발자가 합류해도 충격을 받아 도망가지 않을 겁니다.

변경 사항

• preferred_language → 이제 enrichment_language
• arbitration_mode → 지능형 충돌 해결 로 교체
• Lite mode → 아키텍처에서 완전히 제거

왜 중요한가?
죽은 코드가 적을수록 버그가 적고, “이 설정은 뭘 하는 거지?” 같은 질문도 줄어듭니다.

혜택

시작하기

백업

ledgermind-mcp run --path /path/to/v3.0/memory

업그레이드

pip install --upgrade ledgermind

초기화

ledgermind init

Feature Roadmap (Confidence & Evidence)

v3.3 개발에 대한 회고

“v3.3을 시작했을 때, 나는 생각했다: ‘몇 가지 기능, 약간의 최적화, 한 달 안에 릴리즈.’”

현실: 497개의 커밋, 프로덕션에서 발생한 3개의 치명적인 버그, SQLite 락을 디버깅하느라 밤을 새운 것, 그리고 수많은 커피.

하지만 5,500+ OPS 로 실행되는 검색, 단 한 번도 락이 걸리지 않은 백그라운드 워커, 그리고 시스템이 자동으로 의사결정 패턴을 “이해”하는 모습을 보니, 그 모든 것이 가치 있었다.

LedgerMind v3.3.2는 단순히 “새 버전”이 아니다. 신뢰할 수 있는 시스템이다.

이제 멋진 무언가를 만들어 보라.

v3.0.0부터 v3.3.2까지 497개의 커밋을 분석하여 작성된 기사이다. 저자는 이틀 동안 잠을 못 잤지만 내일은 따라잡을 것이다.

P.S. 버그를 발견하면 — 이슈를 열어 주세요. 우리는 빠릅니다. 약속합니다.

P.P.S. X.com에서 비디오 튜토리얼을 시청할 수 있습니다.

다크‑테마 트윗 임베드 (선택)

var iframe = document.getElementById('tweet-2032901678538580120-188');
if (document.body.className.includes('dark-theme')) {
  iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2032901678538580120&theme=dark";
}