realMemory

지속적 학습이 가능한 LLM 에이전트를 위한 영구 메모리 계층: 재색인 없이 쓰고, 흔적 역학을 통해 망각하며, "수면" 중에 에피소드를 의미론으로 통합하는 로컬 "해마" 메모리.

상태: v0.4 — 모든 프로세스가 공유하는 단일 SQLite 저장소, 전역/프로젝트 메모리 범위, 하이브리드 FTS5 검색, 실제 텍스트로 보정된 임계값.

요점 한 줄 요약

LLM은 고정된 채로 유지된다("피질"). realMemory는 분리된 가변 모듈("해마")이다:

• 참신성 게이트 쓰기: 알려진 사실은 강화되고, 관련 사실은 연결되며, 새로운 사실은 새 흔적을 할당한다. 다르게 표현된 문장은 결코 쌓이지 않는다.

• 공유 + 프로젝트별 메모리: 모든 흔적은 범위(global 또는 프로젝트 이름)를 지닌다. 회상은 현재 프로젝트와 global을 함께 보며, 문맥을 섞지 않는다.

• 흔적 역학에 의한 망각: 각 흔적의 보존은 지수적으로 감쇠하고, 강화는 수명을 연장하며, 충분히 강화된 에피소드는 의미론적 흔적으로 승격한다(느린 감쇠). 망각 곡선은 크론 작업이 아니라 시냅스의 속성이다.

• 공짜로 얻는 연상 그래프: 함께 회상된 것은 가소성(STDP 유사 규칙)에 의해 결합된다. 다중 홉 탐색은 LLM 개체 추출이 아니라 사용 통계에서 생겨난다.

• 하이브리드 검색: 정확한 토큰 검색(FTS5)이 임베딩을 보완한다. 코사인 유사도가 낮아도 오류 ID, 패키지 이름, 코드를 찾아낸다.

• 수면: 오프라인 통합이 적격 흔적을 커밋하고, 약한 연결을 감쇠/정리하며, 상태를 승격한다. 모든 상태는 하나의 SQLite 데이터베이스에 존재한다. MCP 서버와 훅이 데이터 손실 없이 동시에 실행된다.

Related MCP server: Cortex

빠른 시작

pip install -e ".[dev]"
pytest                # full core test suite
python -m realmemory.eval.bench_recall --facts 1500 --queries 200   # synthetic
python -m realmemory.eval.bench_real                                # real-text (fastembed)

from realmemory import Hippocampus, MemoryConfig

hippo = Hippocampus.open("./rm_data", config=MemoryConfig.dev())
hippo.remember("The project uses PostgreSQL 16 with alembic migrations",
               scope="myproject")            # a project-scoped fact
hippo.remember("The user prefers concise answers") # global by default

packet = hippo.recall("which database does the project use?", scope="myproject")
for item in packet.items:
    print(f"[{item.confidence:.2f}] ({item.source}) {item.text}")
if packet.abstained:
    print("no trustworthy memories")     # abstention instead of hallucination

hippo.consolidate()   # "sleep": commit traces, decay weak links

로컬 임베더

기본적으로 코어는 결정론적 HashingEmbedder(모델 없음)를 사용한다. 프로덕션 로컬 의미론적 임베더는 fastembed(ONNX Runtime, CPU)이다:

pip install 'realmemory[local]'

• 모델: paraphrase-multilingual-MiniLM-L12-v2, dim=384, 러시아어+영어.

• 모델 캐시: ~/.cache/realmemory/fastembed (~240 MB), 한 번 다운로드됨.

• 측정된 부하: 프로세스 RAM ~580 MB; CPU에서 텍스트당 ~65–75 ms; 전체 회상 ≈ 77 ms. 에이전트에게는 보이지 않는다.

• 비대칭 처리가 지원된다: 사실은 embed()로, 쿼리는 embed_query()로 인코딩된다.

• 게이트 임계값은 모델 이방성별로 보정된다. 임계값 프로필은 FastEmbedProvider.recommended_thresholds에 있으며, 서버 시작 시 적용되고, 실제 텍스트 벤치마크(아래 참조)에서 도출된다.

ZCode / Claude Code(MCP)에 연결하기

클라이언트 구성에 사용자 범위 stdio 서버를 등록하십시오:

"realmemory": {
  "type": "stdio",
  "command": "/path/to/venv/Scripts/python.exe",
  "args": ["-m", "realmemory.api.mcp_server",
           "--path", "/path/to/rm_data",
           "--embedder", "local"]
}

에이전트 도구(인지 행동으로 명명됨): recall(query,k,project) · memorize(text,kind,related_ids,project) · reflect(memory_ids,reward) · revise(old_id,new_text) · introspect() · dream_log().

공유 + 프로젝트별 메모리: 모든 흔적은 범위 — global(선호도, 정체성) 또는 프로젝트 이름으로 태그가 지정된다. 프로젝트는 자동으로 감지된다(REALMEMORY_PROJECT → ZCODE_PROJECT_DIR → .git을 포함한 현재 디렉터리). project 인자나 --project로 명시적으로 전달할 수도 있다. recall은 현재 프로젝트 + global을 검색하며, 다른 프로젝트는 절대 섞이지 않는다.

별도의 브레인 간 전체 네임스페이스 격리는 Hippocampus.open(path, namespace=...) / --namespace로 사용할 수 있다.

데이터베이스는 임베더 마커(db_meta)를 저장하며 다른 임베더로 열기를 거부한다. 이전 벡터와 새 벡터는 코사인으로 비교할 수 없기 때문이다.

자동화: 에이전트가 실제로 사용하게 만들기

기본적으로 설치되는 세 가지 메커니즘:

1. 스킬/지침 — 언제 회상/기억/반성할지 설명하며 모든 세션 컨텍스트에 로드된다.

2. SessionStart 훅 → python -m realmemory.hook_cli brief — 짧은 메모리 상태를 주입한다: 현재 프로젝트 + global의 의미론적 사실과 지속적 에피소드 흔적, ~600자 예산.

3. Stop 훅 → python -m realmemory.hook_cli sleep — 각 응답 후 통합을 수행한다. 데이터베이스 상태에 따라 조절된다(마지막 수면 이후 변경 사항이 없으면 건너뜀). ~0.3초 걸리며 임베더 모델을 로드하지 않는다.

훅과 MCP 서버는 동시에 안전하게 실행된다. 모든 상태는 SQLite에 있으며, 동시 "수면"은 트랜잭션으로 직렬화된다.

운영

• 백업: 모든 '수면' 전에 데이터베이스가 <store>/backups/로 복사되고(일관된 sqlite 백업 API), 마지막 10개 복사본이 유지된다(backups_keep; 0이면 비활성화). 스키마 마이그레이션 시 자동 안전 복사본이 먼저 만들어진다.

• 스키마 버전은 db_meta.schema_version에 기록된다.

• 훅 실패는 조용히 넘어가지 않는다: 실패한 훅은 세션의 stderr에 출력하고 저널에 hook_error 이벤트를 남기며, 보고서에서 볼 수 있다.

• 학습 규율: 보고서는 reflect/recall을 보여준다. ~0.1 미만이면 에이전트가 회상된 기억을 거의 평가하지 않아 감쇠/승격이 맹목적으로 실행된다.

• 프로젝트 라우팅은 한 번의 호출로 확인된다. introspect가 현재 감지된 프로젝트를 보여준다.

관찰 가능성("메모리가 시간에 따라 어떻게 작동하는지")

모든 이벤트는 데이터베이스 내부의 저널에 추가된다: 쓰기, 회상(지연 시간, 기권, 신뢰도), 피드백, 전체 지표를 포함한 통합. 언제든 전체 보고서:

python -m realmemory.report --path ./rm_data [--json report.json]

표시 내용: 유형/범위/상태별 메모리 증가, 참신성 게이트 결정 이력, 기권 비율과 p50/p95 회상 지연 시간, 강화된 것, 사라지는 에피소드, 수면 간 보존 역학, 훅 실패.

Phase 0 결과(실제 실행)

합성 벤치마크(bench_recall, 해싱 임베더, dim=2048):

실제 텍스트 벤치마크(bench_real, fastembed MiniLM dim=384, RU/EN 사실 103개, 쿼리 89개 — 패러프레이즈, 정확 토큰, 노이즈):

합성 벤치마크에서 얻은 교훈: 이 벤치마크는 1.000을 기록했지만 실제 텍스트에 대한 기본 임계값은 거의 모든 것을 몇 개의 덩어리로 병합했다. 이제 보정은 벤치마크 분포에서 도출되어 임베더 프로필에 있다. 동일한 실제 텍스트 벤치마크에는 단순한 전체 스캔 코사인 베이스라인이 포함된다: 파이프라인은 정확 토큰에서 명확히 승리하고(1.000 vs 0.800), 패러프레이즈에서는 동등하며, 현재 순수 임계값보다 덜 공격적으로 기권한다 — docs/ARCHITECTURE.md §7.2 참조. 합성 데이터에서 30k 지점의 회상 품질 절벽에 대한 솔직한 결과를 담은 규모 스윕(10k–50k 흔적): §7.3.

세부 사항과 부정적인 Hamming-SDM 결과는 docs/ARCHITECTURE.md §3 및 §7에 있다.

테스트: 122개 통과.

아키텍처

요약: L1 — SDRVotingIndex, SDR 단위의 역색인에 대한 포인터 투표(용량 + 후보), L2 — 동일한 단위에 대한 어셈블리 네트워크(연관, 완성, 다중 홉), 그 위에 정확한 임베딩 재순위화, 참신성 게이트, 감쇠 정책, 오프라인 통합기("수면")가 얹힌 구조.

모듈 인터페이스는 docs/CONTRACTS.md에 정의되어 있고, 연구 배경과 출처는 docs/RESEARCH.md에 있다.

프로젝트 구조

src/realmemory/
├── encoding/     # embedders, SDR encoding
├── core/         # L1 SDRVotingIndex, L2 AssemblyNetwork, plasticity
├── policies/     # novelty gate, trace decay/promotion
├── store/        # SQLite storage (traces, edges, eligibility, events)
├── api/          # MCP server
└── eval/         # benchmarks

라이선스

MIT