origin-memorycore

English | 简体中文

MemoryCore는 LLM 에이전트를 위한 메모리 거버넌스 계층입니다.

에이전트는 메모리를 빠르게 축적합니다. 선호도, 사실, 결정 등이 쌓이면서 유지 관리되지 않은 메모리는 조용히 악화됩니다. 중복이 쌓이고, 오래된 사실이 남아 있으며, 핫 티어가 가득 차서 쓰기를 거부하기 시작합니다. MemoryCore는 이런 상황을 방지합니다.

이중 티어 메모리 시스템으로 동작합니다:

• 핫 티어 — 자주 사용되는 행동 지식(선호도, 규칙, 수정 사항)을 빠른 로컬 파일에 보관하며 항상 컨텍스트에 포함됩니다.

• 콜드 티어 — 빈도가 낮은 사실을 자동으로 마이그레이션하여 인프로세스 SQLite 엔진(또는 구성한 경우 원격 메모리 서비스)에 저장합니다.

그 사이에서 거버넌스 코어가 메모리를 건강하게 유지합니다:

• 쓰기 시 중복 제거 — 유사한 사실은 저장 전에 병합되며 중복 생성되지 않습니다.

• 용량 제어 — 소프트/하드 임계값이 핫 티어가 가득 차기 전에 오버플로를 트리거하여 쓰기 거부가 발생하지 않도록 합니다.

• 콜드 티어 거버넌스 — 주기적인 중복 제거/정리 패스로 콜드 티어가 커져도 검색 가능한 상태를 유지합니다.

• 휴지통 — 삭제된 항목은 30일의 유예 기간을 갖습니다. 휴지통에 있는 항목을 회수하면 복원됩니다.

결과: 핫 티어는 예산 범위 내에 유지되고, 콜드 티어는 검색 가능한 상태로 유지되며, 에이전트가 아무리 많은 메모리를 축적해도 메모리는 유지 관리 가능한 상태로 남습니다.

MCP(Model Context Protocol) streamable-http / stdio 표준을 기반으로 구축되었습니다. 모든 MCP 클라이언트와 작동하며, Hermes Agent로 테스트되었습니다.

기능

• 메모리 거버넌스(핵심) — 콜드 티어 데이터 무결성을 위한 3중 보호 계층:

  • 콜드 쓰기 중복 제거: 콜드 티어에 쓰기 전에 의미론적 회수(semantic recall) + LLM 판정으로 중복을 확인하고, 중복 항목을 생성하는 대신 기존 항목을 업데이트합니다.

  • 용량 하드 게이트: 콜드 티어는 소프트 한도(6000개 항목, 유지 관리 패스 1회 트리거)와 하드 한도(10000개 항목, 유지 관리 루프 강제)를 적용하여 무한 증가를 방지합니다.

  • 휴지통(trash_store.py): 삭제된 콜드 티어 항목은 30일 만료 기한과 함께 ~/.memorycore/trash.json으로 이동합니다. 새로운 의미론적 증거와 함께 휴지통 항목을 회수하면 복원됩니다("recall to revive").

• 콜드/핫 라우팅 — 모든 쓰기는 분류됩니다: 중요도가 높거나 선호도에 가까운 내용 → 핫(로컬); 빈도가 낮은 사실 → 콜드(원격); 오래된 상태 기록 → 폐기.

• 6단계 오버플로 — 용량 기준선 → 중복 제거 → 오래된 항목 필터링 → 병합 → 안전 쓰기(콜드 먼저, 그다음 로컬 삭제) → 검증.

• 콜드 티어 유지 관리 — 중복 병합, 오래된 항목 정리, 충돌 해결, 임베딩 무결성 검사.

• 용량 제어 — 소프트 임계값(쓰기 전에 오버플로 1회) / 하드 임계값(오버플로 강제) / 목표 비율. 기본값: 5000자 제한의 60% / 80% / 40%.

• 우아한 성능 저하 — 콜드 티어에 연결할 수 없나요? 쓰기는 명시적으로 실패하며(절대 조용히 유실되지 않음), 오버플로는 로컬 항목을 유지하고, 상태 확인은 cold.error와 함께 로컬 상태를 반환합니다.

• 코어 수정 없음 — 드롭인 컴패니언으로 설계되었습니다. 에이전트의 내장 메모리 도구는 계속 작동합니다.

Related MCP server: AI Long-Term Memory MCP Server

아키텍처

┌─────────────────────────────── Mac / local ──────────────────────────────┐
│  LLM agent (e.g. Hermes)                                                 │
│    │  MCP client                                                         │
│    ▼                                                                     │
│  MemoryCore MCP server                                                   │
│    ├─ local_store.py        hot tier: MEMORY.md / USER.md (chars-based)  │
│    ├─ classifier.py         cold/hot/stale routing rules                 │
│    ├─ overflow.py           six-step overflow                            │
│    ├─ maintenance.py        cold-tier governance                         │
│    └─ cold_store_client.py  →  LocalBackend (SQLite, in-process)         │
│                               or RemoteBackend (MCP streamable-http)     │
└──────────────────────────────────────────────────────────────────────────┘
                     LocalBackend: mnemosyne-memory (in-process engine)
                     RemoteBackend: remote MCP memory service

Optional (Hermes Agent only): hermes-plugin/memorycore-prefetch
  ┌───────────────────────────────────────────────────────────────────────┐
  │ MemoryProvider plugin (single-model qwen3, enabled by default)        │
  │   system_prompt_block → static index (always active)                  │
  │   prefetch → ColdStoreClient.recall_results(top_k=20)                 │
  │            → dense ranking → session + hot-tier dedup → top-5         │
  │   Disable: MEMORYCORE_PREFETCH_ENABLED=0                              │
  └───────────────────────────────────────────────────────────────────────┘

빠른 시작

사전 요구 사항

• ollama — 임베딩 API (설치: https://ollama.com)

• qwen3-embedding:0.6b — 권장 임베딩 모델 (1024차원)

# Install ollama (macOS/Linux)
curl -fsSL https://ollama.com/install.sh | sh

# Pull the embedding model
ollama pull qwen3-embedding:0.6b

설치 및 실행

pip install "origin-memorycore @ git+https://github.com/moonandecho/origin-memorycore.git"

# That's it! MemoryCore runs with ollama for embeddings:
#   - Hot tier:  MEMORY.md / USER.md (default ~/.hermes/memories)
#   - Cold tier: SQLite via mnemosyne-memory (default ~/.memorycore/data/)
#   - Embedding: qwen3-embedding:0.6b via ollama (http://localhost:11434/v1)
python -m memorycore.server          # stdio transport (default)

데이터 디렉터리 구조 (모두 ~/.memorycore/ 아래):

~/.memorycore/
├── data/          # SQLite database (MNEMOSYNE_DATA_DIR)
└── ...

MNEMOSYNE_DATA_DIR로 재정의할 수 있습니다.

모델 전환

기본 임베딩 모델은 qwen3-embedding:0.6b(1024차원)입니다. 환경 변수를 설정하여 어떤 ollama 모델이든 사용할 수 있습니다:

export MEMORYCORE_EMBED_URL="http://localhost:11434/v1"
export MEMORYCORE_EMBED_MODEL="nomic-embed-text"   # or your preferred model

또는 OpenAI 호환 임베딩 API를 지정할 수 있습니다:

export MEMORYCORE_EMBED_URL="https://api.openai.com/v1"
export MEMORYCORE_EMBED_MODEL="text-embedding-3-small"

MCP 클라이언트에 등록합니다(Hermes Agent config.yaml 예시):

mcp_servers:
  memorycore:
    command: python
    args: ["-m", "memorycore.server"]

원격 모드(선택 사항)

로컬 엔진 대신 공유 원격 Mnemosyne MCP 서비스를 선호한다면 MEMORYCORE_COLD_BACKEND=remote로 설정하세요:

export MEMORYCORE_COLD_BACKEND=remote
export MNEMOSYNE_URL="http://your-memory-service:9000/mcp"
python -m memorycore.server

노출되는 도구:

Hermes 통합 — 턴별 프리페치

MCP 서버는 클라이언트에 독립적입니다. Hermes Agent에는 콜드 티어 이중 채널 액세스를 제공하는 선택적 컴패니언 플러그인이 있습니다:

이중 채널 설계

• 정적 인덱스 채널(항상 활성, 제로 오버헤드) — 사용 가능한 주제를 나열하는 시스템 프롬프트 블록(MEMORYCORE_INDEX_TOPICS로 구성, 쉼표로 구분)으로, 필요 시 memorycore_recall(query)를 사용하여 회수하라는 안내를 포함합니다.

• 턴별 프리페치 채널(기본 활성화) — 매 턴마다 콜드 티어를 회수하고, 밀집 점수로 순위를 매긴 뒤 상위 5개를 컨텍스트에 주입하여 에이전트가 말하기 전에 관련 내용을 "기억"하게 합니다. 비활성화하려면 MEMORYCORE_PREFETCH_ENABLED=0으로 설정하고 필요 시 회수만 사용하세요.

프리페치 파이프라인

query → preprocess → cold-tier recall (20 candidates)
  → dense ranking (qwen3) → top-5
  → session dedup → hot-tier dedup → inject into context

MemoryCore는 단일 모델 qwen3 아키텍처(리랭커 없음)를 사용합니다. qwen3의 밀집 점수는 배치 내 상대 순위를 매기는 데 사용됩니다. 절대 임계값은 없으며, 밀집 점수 기준 상위 5개 후보가 중복 제거 후 항상 주입됩니다.

우아한 성능 저하

ollama에 연결할 수 없을 때(설치되지 않음, 실행 중 아님, 모델 미풀) 프리페치는 조용히 빈 문자열을 반환합니다. 대화는 주입된 메모리 없이 진행되며 사용자에게 오류가 표시되지 않습니다. DEBUG 수준 로그가 프로브 실패를 기록합니다.

배포(Hermes Agent)

# 1. install origin-memorycore (provides the cold tier + ColdStoreClient)
pip install "origin-memorycore @ git+https://github.com/moonandecho/origin-memorycore.git"

# 2. put the plugin in Hermes' user plugin dir
mkdir -p ~/.hermes/plugins
cp -r hermes-plugin/memorycore-prefetch ~/.hermes/plugins/

# 3. activate (takes effect next session)
hermes config set memory.provider memorycore-prefetch

배포 후 세 가지 포스처:

플러그인 구성

요구 사항 및 참고 사항:

• Hermes 전용: 플러그인은 Hermes 런타임 모듈(agent.memory_provider)을 가져오며 독립 패키지로는 작동하지 않습니다 — MemoryCore의 Hermes 통합 측면입니다. 자세한 내용: hermes-plugin/memorycore-prefetch/README.md.

• 모든 회수는 5초 타임아웃을 유지합니다. 실패는 빈 주입으로 조용히 처리되며 대화를 차단하지 않습니다.

핫 티어 거버넌스

핫 티어(MEMORY.md / USER.md)는 매 턴 컨텍스트에 주입되므로 작고 최신 상태로 유지되어야 합니다. MemoryCore는 6단계 오버플로 위에 세 가지 메커니즘을 추가하여 과거 기록이 쌓이기만 하는 대신 결정적으로 은퇴하도록 합니다:

핫 티어 메타데이터 에이징

• 사이드카 메타데이터: MEMORY.meta.json / USER.meta.json이 .md 파일 옆에 있으며, 항목 콘텐츠의 SHA-256을 키로 사용합니다. 원자적 쓰기와 파일 잠금으로 프로세스 간 안전을 보장하며, §로 구분된 .md 형식은 그대로 유지되므로 호스트 메모리 도구는 변경 없이 계속 작동합니다.

• 모든 항목은 state(과거 결정/상태 기록) 또는 rule(원칙/선호도)로 유형화됩니다:

  • state: 작성 후 7일이 지나면 콜드 티어로 은퇴합니다(STATE_TTL_DAYS로 구성 가능).

  • rule: 나이로 은퇴하지 않습니다. 업데이트 없이 30일이 지나면 긴 항목(>200자)이 LLM 압축 후보가 됩니다(RULE_COMPRESS_DAYS로 구성 가능). 또한 규칙은 아래 무효화 신호 사다리를 통해 지속 가능한 출구를 얻습니다. 활성 선호도를 잘못 은퇴시키는 일은 없습니다.

• 항목 콘텐츠가 변경되면 키도 변경됩니다. 다음 조정(reconcile)에서 새 콘텐츠를 다시 유형화하고 고아 키를 가비지 컬렉션합니다.

이중 쓰기 진입점 거버넌스

• store_fact 쓰기 진입점: 완료된 결정/상태 기록처럼 보이는 콘텐츠(날짜와 완료 표시(예: 拍板/已配置)가 있고 행동 지침이 없는 경우)는 콜드 티어로 직접 라우팅됩니다. 핫 티어에 들어가지 않습니다.

• 플러그인 on_memory_write 직접 쓰기 채널: 내장 메모리 도구의 add/replace 후 항목이 즉시 유형화됩니다. state 항목은 백그라운드에서 콜드 티어로 마이그레이션됩니다(중복 제거 → 콜드 쓰기 확인 → 핫에서 제거; 콜드 실패 시 항목은 7일 백스톱(state stamp)으로 유지됩니다). 이는 사용량 임계값과 무관하게 실행됩니다. 단일 워커 스레드가 제한된 큐(크기 128)를 처리합니다. 큐가 가득 차면 쓰기는 건너뛰고 다음 오버플로 조정이 백스톱으로 스탬프합니다.

메타데이터 우선 오버플로

각 오버플로 실행은 먼저 메타데이터를 조정하고(유형화되지 않은 레거시 항목 스탬프, 고아 가비지 컬렉션), 그다음 메타데이터 기준으로 항목을 은퇴시킵니다. 키워드는 유형화되지 않은 항목의 폴백으로만 남습니다. 사이드카 실패는 키워드 경로로 성능이 저하되며 오버플로를 차단하지 않습니다.

규칙 무효화 신호(계층형 보호)

순수 rule 항목으로만 이루어진 핫 티어는 설계상 출구가 없습니다("선호도를 가라앉히지 않음"). 따라서 편집되지 않는 짧은 규칙은 영원히 남아 결국 티어를 가득 채우게 됩니다. MemoryCore는 압력 사다리로 이 간극을 메웁니다: 모든 오버플로 실행은 실제 사용량(기준선)을 측정하고 압력이 상승함에 따라 더 깊은 출구를 엽니다(대응). 다섯 가지 관찰 가능한 신호가 자격과 순서를 결정하고, 압력이 실행 여부를 결정합니다:

계층형 보호: A-클래스 메타 규칙(행동/상호작용/문체 지침), 레드라인 규칙 및 중요도 ≥ 0.9 항목은 절대 S2/S4/S5를 적용받지 않으며, 병합 또는 압축만 수행됩니다. 스텁 포인터는 자체 수명 주기를 가지므로(하드 압력 시 오래된 순서부터 GC, 콜드 티어는 절대 건드리지 않음) 포인터가 티어를 두 번 채우는 일은 없습니다. 모든 탈출 경로는 콜드-쓰기-우선입니다. 로컬 항목은 콜드 티어가 확인한 후에만 변경되며, 실패 시 원본이 유지됩니다. 신호를 사용할 수 없으면(활동 로그 없음, LLM 키 없음) 이 단계별 구조는 추측하는 대신 이전 동작으로 폴백합니다.

상수(memorycore/core/config.py): RULE_RETYPE_DAYS=60, RULE_STUB_IDLE_DAYS=45, ACTIVITY_WINDOW_DAYS=30, MAX_STUB_PER_RUN=3, STUB_MAX_CHARS=40, IMPORTANCE_PROTECT=0.9.

상태 점검: memorycore_memory_audit

핫 티어의 모든 항목을 유형, 수명, 폐기 계획, 유지/싱크 분류와 함께 나열하는 읽기 전용 도구로, 싱크할 대상을 찾지 못하는 오버플로를 진단하기 위한 관측 가능성 앵커입니다.

규모 테스트 및 최적화 결과

MemoryCore는 만 개 항목의 콜드 티어 규모에서 스트레스 테스트와 리콜 최적화를 거쳤습니다(격리된 테스트 환경, 프로덕션 데이터와 완전히 분리, 재현 가능한 결과).

쓰기 및 용량

쿼리 지연 시간 — top_k=5에서 중앙값 48ms; 만 항목 규모가 백 항목 규모와 일치하며 지연 시간 회귀가 없습니다.

리콜 품질 — 세 가지 프로브:

1. 정확히 일치(자기 리콜): 20/20이 top-1 적중 — 정확히 일치 검색은 그대로 유지됩니다.

2. 노이즈 제거(무관한 쿼리): 평균 top-1 밀집 점수 0.056, 대부분 0.0 반환 — 무관한 콘텐츠가 결과에 거의 유출되지 않습니다.

3. 짧은 쿼리 리콜(전 → 후) — 핵심 최적화 결과:

최적화된 내용: 주제 밀도가 높을 때 고정 후보 잘림 k=max(top_k, 20)으로 인해 상세 메모리가 후보 풀에서 밀려나 짧은 쿼리가 이를 리콜하지 못했습니다. 수정은 후보 잘림을 k=max(top_k*4, 300)으로 확대하고, 반환을 잘라내기 전에 리콜 진입점에서 내부적으로 후보를 확장합니다 — 모든 리콜 채널(턴별 프리페치 + 온디맨드 리콜)이 단일 수정의 혜택을 받습니다. 수정은 리콜 단계에만 국한되며, 랭킹 로직은 변경되지 않아 동작이 예측 가능하고 되돌릴 수 있습니다.

참고: 테스트는 합성 10k 항목 데이터베이스(80개의 "골든" 메모리 + 9920개의 일일 로그 어조 필러 메모리, 프로덕션과 동일한 구성)로 실행되었습니다. 프로덕션 데이터는 건드리지 않았습니다.

sqlite-vec 사용자 참고 사항

Mnemosyne 콜드 티어에 sqlite-vec 벡터 인덱싱을 활성화하는 경우, beam.py의 _wm_vec_search_sqlite는 원시 유사도 공식 sim = 1 - distance / (2 * EMBEDDING_DIM)을 사용하는데, 이는 float32 거리를 ~1.0으로 붕괴시켜 동적 임계값을 사실상 무용하게 만듭니다(모든 결과가 통과).

패치: float32 분기에서 공식을 sim = 1 - d² / 2로 교체하세요. 그러면 정규화된 벡터에 대해 정확한 코사인 유사도가 나오고 올바른 임계값 동작이 복원됩니다.

콜드 스토어 계약

다음 다섯 가지 MCP 도구를 노출하는 모든 서비스는 콜드 티어로 작동할 수 있습니다:

전체 계약 및 참조 클라이언트는 examples/cold-store-contract.md를 참조하세요.

구성

용량 상수는 memorycore/core/config.py에 있습니다(CHAR_LIMIT_*, SOFT_THRESHOLD, HARD_THRESHOLD, TARGET_RATIO).

작동 방식

1. 쓰기 — store_fact가 내용을 분류합니다:

   • 중요도 ≥ 0.8 또는 핫 키워드(선호도 / 규칙 / 수정 사항 / 레드라인)와 일치 → hot, 로컬 유지

   • 오래된 마커(짧은 항목, 예: "已修复 / fixed") → dropped(마이그레이션되지 않음)

   • 그 외 → cold, 원격 서비스에 직접 기록

2. 오버플로 — 핫 사용량이 소프트 임계값을 넘으면 오버플로가 저빈도 항목을 콜드 티어로 마이그레이션합니다. 하드 임계값에서는 대상 값 이하가 될 때까지 강제 오버플로를 수행합니다. 순서는 항상 콜드 먼저 쓰고, 확인한 다음 로컬 삭제입니다. 콜드 티어가 실패해도 손실되는 것이 없습니다.

3. 유지 관리 — 주기적인 콜드 티어 순회를 통해 중복 병합, 오래된 항목 제거, 충돌 해결, 임베딩 무결성 검증을 수행합니다.

라이선스

MIT © 2026 moonandecho

타사 라이선스

• mnemosyne-memory — MIT, AxDSan 제작. LocalBackend가 사용하는 프로세스 내 메모리 엔진.

• MCP Python SDK — MIT.

• ollama — MIT. 로컬 임베딩 API 서버.

• qwen3-embedding — Apache-2.0, Alibaba Cloud 제작. 기본 임베딩 모델(번들 아님, ollama로 가져옴).