증류창고 — distill-kura

에이전트를 위한 장기 기억. 축적이 아니라 증류.

회상은 의미로 작동하고, 기록은 증거로 검증되며, 서버 하나가 여러 개의 분리된 기억을 담을 수 있다 — 에이전트 모드마다 하나씩 — 그래서 모드를 바꾸면 에이전트가 기억하는 내용이 바뀐다.

DeepSeek Harness 플러그인, 다른 모든 호스트를 위한 MCP 서버, HTTP 서비스, 그리고 Python 라이브러리로 제공된다. 표준 라이브러리만 사용한다. 벡터 데이터베이스도, 임베딩도, 프레임워크도 없다.

        ┌── recall ──────────────────────────────────────────────┐
        │  question → whole index in one prompt → picked slugs   │
        │           → walk [[links]] → the neighbourhood         │  ~0.4 s
        └────────────────────────────────────────────────────────┘
        ┌── distil ──────────────────────────────────────────────┐
        │  journal → classed evidence → candidates → GATE        │
        │  → new? → composed → draft → judged → poured           │
        └────────────────────────────────────────────────────────┘

왜 존재하는가

두 가지 실패가 에이전트의 장기 기억을 죽인다. 그리고 그 둘은 정반대 방향에서 죽인다.

키워드 검색은 필요한 것을 놓친다. *"SSD 추론 칩"*에 대한 질문은 *"2.6T 모델을 SSD 티어에서 실행하기"*라는 기억과 단어 하나도 공유하지 않는다 — 하지만 둘은 같은 주제다. 단어 검색은 아무것도 반환하지 않고, 에이전트는 공허에서 대답한다. 여기서의 해결책은 임베딩이 아니라 인식이다: 전체 인덱스(기억당 한 줄, 인식 트리거로 작성됨)가 하나의 프롬프트에 들어가고, 작은 모델이 질문과 관련된 것을 지목한다. 약 500개 기억의 인덱스는 약 6k 토큰 — 현대 컨텍스트 윈도우의 몇 퍼센트에 불과하며, 프리픽스 캐시에 상주한다.

모든 것을 기록하면 저장소가 오염된다. 에이전트가 주장을 한다. 순진한 증류기가 그 주장을 사실로 기록한다. 다음 에이전트가 그것을 진실로 읽고 더 큰 확신을 가지고 반복한다. 그 루프는 자기 강화적이며, 프롬프트 지시로는 막을 수 없다 — 추정이 아니라 측정된 사실이다. 그래서 쓰기 경로는 결정론적 Python으로 검증된다: 모든 후보 기억은 원자료에 문자 그대로 존재하는 인용문을 반드시 포함해야 하며, 출처가 태그로 표시된다.

문자 그대로 발견되지 않은 인용문은 폐기된다. 살아남은 인용문이 없는 후보는 버려진다. 뒤에 [TOOL]이 없는 숫자는 제거된다. [USER] 인용문이 살아남지 않았는데 인간이 결정했다고 주장하는 텍스트는 마지막 관문에서 거부된다. 아이디어는 환영한다 — 시드 파일로 가며, 저장소에는 절대 들어가지 않고, 이후 증거가 확인할 때만 승격된다.

Related MCP server: Synapto

빠른 시작

git clone https://github.com/lna-lab/distill-kura && cd distill-kura
pip install -e .                       # or just run: python3 -m distill_kura.cli

cp kura.example.toml kura.toml         # edit: one model endpoint is enough to start
kura init main --path ~/kura/main      # create an empty store
kura serve                             # http://127.0.0.1:8085

curl -s -X POST localhost:8085/recall -H 'content-type: application/json' \
     -d '{"question":"what did we decide about the archive disk?","hops":1}'

인덱스를 착용하라. 에이전트가 항상 무엇이 알려져 있는지 알 수 있도록:

kura weave                             # build the three-layer cloth
kura prefill                           # the block to put in the system prompt

에이전트 트랜스크립트를 공급하라:

kura distill run      # drink a batch → candidates → gate → drafts
kura distill drafts   # look at what it wants to write
kura distill drain    # the scribe re-reads each draft cold: pour / fix / toss
kura distill night    # stay resident and do it whenever things go quiet

drain(또는 수동 실행 pour) 전에는 아무것도 저장소에 들어가지 않는다. 초안은 HTML 주석에 증거를 담고 있어서, 기억이 왜 존재하는지 항상 볼 수 있다.

상주 지도

도구 기반 회상은 *"X에 대해 무엇을 아는가?"*에 답한다 — 하지만 에이전트가 질문하기로 결정한 후에만. 그것은 에이전트가 생각조차 하지 못하는 질문에는 절대 답하지 않는다: 여기에 아무것도 있는가? 지도를 볼 수 없는 에이전트는 무엇을 놓치고 있는지 모르므로 추측한다. 그리고 당신의 가정에 대한 자신 있는 추측은 정확히 이 프로젝트가 막으려는 실패다.

그래서 인덱스도 착용된다: 시스템 프롬프트의 상주 블록으로, 매 턴마다.

kura weave      # re-weave the index into the three-layer cloth
kura prefill    # print the block a host should inject

세 개의 계층, 세부사항은 최근 것에만 가치가 있으므로

맹검 A/B 테스트 — 질문 20개, 두꺼운 인덱스 대 슬림 인덱스, 어느 쪽인지 모른 채 채점 — 가 형태를 결정했다:

원칙 줄은 두 인덱스에서 바이트 단위로 동일했는데, 슬림 인덱스가 여전히 그 구간에서 이겼다: 더 가벼운 주변부가 상주 줄을 더 잘 작동하게 만든다. 세부사항은 통찰의 원천이 아니다. 그것은 아직 움직이는 곳에서만 자리를 얻는다.

트리거 줄은 scribe 모델이 작성하며, 설명 및 예산을 키로 하는 원장에 캐시된다. 그래서 정상 상태에서 재직조는 비용이 들지 않는다. 모델에 연결할 수 없으면 직조기는 대신 기계적으로 잘라낸다 — GPU가 다운되었다고 기억 시스템이 공백이 되어서는 안 된다.

나이는 mtime이 아니다. cp -r, 복원 또는 체크아웃은 모든 타임스탬프를 재설정하고, 전체 인덱스가 "최근"으로 바뀌며, 아무것도 잘리지 않고, 메커니즘이 조용히 스스로 꺼진다. 그래서 직조기는 기억 내부에 쓰인 날짜를 선호하고, 저장소의 5분의 1이 하루 달력 날짜를 공유하는 mtime은 불신한다.

어디에 위치하는가, 그리고 왜 그것이 캐시 결정인가

- id: kura
  name: distill-kura
  config: { store: eq, promptOrder: -50 }   # before the persona

프리픽스 캐시는 첫 번째 변경된 바이트부터 손실된다 — 로컬 서버 하나에서 측정: 동일한 4,029토큰 전문은 0.68초에서 0.14초로 재가격화되고, 끝에 추가하면 0.14초를 유지하며, 앞에 한 단어만 추가해도 전체 캐시가 손실된다(0.66초). 페르소나는 일반적으로 시계를 담고 있어 매분 변경된다. 지도는 프롬프트에서 가장 큰 블록이며 하루에 몇 번 변경된다. 크고 안정적인 것이 똑딱거리는 것 앞에 간다.

그 블록 자체에는 날짜, 시계, 카운터가 없다 — 그리고 build()는 그런 헤더를 빌드 시점에 거부한다. 3주 후에 신비롭게 느려진 턴을 통해서가 아니라.

절반의 지도를 넘겨주지 않는다

잘린 지도는 가능한 최악의 산출물이다: 완전해 보이고, 절단선 아래의 모든 기억은 존재하지 않는 것처럼 보인다. weave는 예산에 맞추기 위해 최근 창을 줄이겠지만, 줄을 절대 버리지 않는다 — 그리고 어떤 설정으로도 예산에 도달하지 못하면 그렇게 말하고, 더 나은 지도를 유지하며, 무게가 어디에 있는지 알려준다.

호스트에 넣기

MCP instructions 필드는 스펙에서 MAY이며, 9,000토큰 인덱스는 어떤 경우에도 2KB 한도를 통과할 수 없다. 그래서 이 프로젝트는 그렇게 가장하지 않는다.

모드: 하나 이상의 kura

"이것을 만드는 것을 도와줘"와 "이것을 생각해내는 것을 도와줘"를 동시에 서비스하는 단일 기억은 둘 다 제대로 서비스하지 못한다: 디버깅에 도움이 되는 회상은 다음에 무엇을 할지에 대한 대화에서 잡음이다. 그래서 저장소는 디렉토리이고, 모드는 저장소에 매핑된다.

[stores.maker]
path = "~/kura/maker"
label = "maker mode — building things"

[stores.eq]
path = "~/kura/eq"
label = "EQ mode — talking things through"

[modes]
maker = "maker"
eq    = "eq"

모든 라우트는 셀렉터를 받으므로, 하나의 프로세스가 모두를 서비스한다:

curl -s -X POST localhost:8085/recall -d '{"question":"...","mode":"eq"}'
curl -s localhost:8085/index?store=maker
curl -s localhost:8085/s/eq/doctor          # path form, for clients that only vary a base URL

저장소는 기억, 인덱스, 증류기 워터마크를 공유하지 않는다. 모드를 바꾸는 것은 진정으로 기억되는 것을 바꾼다 — 같은 기억을 다른 목소리로 말하는 것이 아니다.

라우팅으로서는 독립적이지만, 기밀성으로서는 아니다. 서버에는 인증이 없으므로, 포트에 도달할 수 있는 모든 프로세스는 서버가 보유한 어떤 저장소든 지명할 수 있다. 에이전트를 바인딩하는 것은 모델을 자기 차선에 가두는 것이다. 프로세스를 막는 것이 아니다. 프로세스당 신뢰 수준 하나 — docs/TRUST.md는 짧고, 개인 저장소를 넣기 전에 읽을 가치가 있다. 놓치기 쉬운 두 경계도 다룬다: 하나의 저널 루트에서 물을 마시는 두 저장소, 그리고 하나의 모델 엔드포인트 뒤에 있는 두 저장소.

DeepSeek Harness와 함께

DSH는 에이전트 프리셋으로 페르소나와 도구를 전환한다. distill-kura는 저장소로 기억을 전환한다. 그것들을 묶으면 하나의 프리셋 변경이 전체 자아를 움직인다:

# .agent-presets/eq/agent.cordis.yml
- id: kura-eq
  name: distill-kura
  config:
    url: http://127.0.0.1:8085
    store: eq            # this preset's memory
    readonly: true       # the CLIENT's own switch: do not even offer a write tool
    # (the store's own `write_policy` is the authority; this just keeps the tool
    #  out of the model's hands. Naming a store already binds the preset.)

allowSwitch를 기본값으로 두면 에이전트는 kura_use도 얻어서, 프리셋 변경 없이 대화 중에 kura 사이를 이동할 수 있다. 도구: kura_recall, kura_read, kura_doctor, kura_list, kura_use, 그리고 kura_remember(저장소가 쓰기 가능할 때만). MCP 브리지와 서비스 행을 위한 isolate 영역 규칙을 포함한 전체 배선은 examples/dsh-presets/에 있다.

페르소나는 호스트의 일이다. 우리의 일이 아니다. 이 프로젝트는 페르소나를 렌더링하거나 주입하지 않는다. 저장소별로 어떤 페르소나 파일이 그와 함께하는지 기록만 하며, GET /profile?store=eq에서 읽을 수 있어서 두 절반이 프리셋 소유자에 의해 보조를 맞출 수 있다. 에이전트 지시사항도 호스트의 AGENTS.md 메커니즘에 남는다 — 이 코드베이스 에서 작업하는 에이전트가 따라야 할 규칙은 이 저장소의 AGENTS.md를 참조하라.

모든 MCP 호스트와 함께

{ "mcpServers": { "kura": {
    "command": "python3", "args": ["-m", "distill_kura.mcp"],
    "env": { "KURA_URL": "http://127.0.0.1:8085", "KURA_STORE": "eq", "KURA_READONLY": "1" }
}}}

자유 모드를 위해 KURA_STORE를 설정하지 않은 채 두어라: 도구는 선택적 store 인수를 받고 kura_use가 세션 동안 전환한다.

모델: 기본값 하나, 역할별로 한 번에 업그레이드

세 대의 기계가 아니라 세 가지 역할:

[models.thinker]만 선언하면 하나의 모델이 세 역할을 모두 수행한다. 다른 하나를 독립적으로 업그레이드하라 — 더 큰 로컬 모델, 또는 온라인 API(모든 OpenAI 호환 /chat/completions; 키는 당신이 이름을 지정한 환경 변수에서 읽히며, 설정에 절대 저장되지 않는다):

[models.thinker]                       # always-on, local, small
url = "http://127.0.0.1:8000/v1"
model = "local-small"

[models.scribe]                        # upgrade just the writing
url = "https://api.example.com/v1"
model = "big-model"
api_key_env = "EXAMPLE_API_KEY"

이것이 처리해주는 두 가지: 추론 노력 방언은 모델 계열마다 다르므로(reasoning_effort, thinking_effort, enable_thinking), 모두 전송된다 — 알 수 없는 것은 템플릿이 무시하고, 기본적으로 딥씽킹에 남아 있는 모델은 전체 예산을 추론에 쓰고 아무것도 반환하지 않을 수 있다. 그리고 헌장 텍스트는 모든 역할의 프롬프트 머리에 바이트 단위로 동일하게 배치되어, 느린 로컬 모델에서 세 역할이 세 번의 프리필을 지불하는 대신 하나의 캐시된 프리픽스를 공유한다.

사고자가 다운되어도 회상은 조용해지지 않는다 — 단어 중복으로 폴백되고 답변에 how=words로 라벨이 붙으며, 도구는 이를 ⚠ degraded로 표시한다. 조용한 성능 저하는 성능 저하보다 더 나쁘다.

메모리의 모습

파일 하나, 사실 하나.

---
name: archive-on-slow-disk
description: the archive lives on the slow disk; the fast one stays scratch
metadata:
  type: project          # user | feedback | project | reference
---

The archive goes on the slow disk. The fast disk is scratch space.

**Why:** the other way round burns write endurance for nothing.
**How to apply:** check which disk a target directory is on before writing there.
Related: [[disk-layout]]

그리고 MEMORY.md의 한 줄:

- [Archive on the slow disk](archive-on-slow-disk.md) — the archive lives on the slow disk; the fast one stays scratch

그 줄은 매번 읽히는 유일한 것이다. 그것은 인식 트리거이지 요약이 아니다: 고유명사, 숫자, ⚠️ 지뢰, 도달한 결론. 어떤 줄이 다른 메모리의 줄과 바꿔도 여전히 자연스럽게 읽힌다면, 그 줄은 제 역할을 하지 못하는 것이다 — kura distill tidy가 기계적으로 감지 가능한 사례를 찾아 다시 쓴다.

kura doctor는 개수, 끊어진 링크, 섬(아무것도 링크하지 않는 메모리), 인덱스 표류를 보고한다. 그것은 신진대사가 필요로 하는 눈이다.

HTTP 표면

모든 라우트는 ?store= / ?mode=, 본문의 store/mode 필드, 또는 /s/<name>/… 경로 접두사를 허용한다. 인증이 없다: 루프백에 바인딩하거나, 앞에 무언가를 두어라.

변경 전에 읽을 가치가 있는 설계 노트

• docs/DESIGN.md — 인식이 검색을 이기는 이유, 게이트가 제공하는 이점, 각 메커니즘을 동기부여한 실패 사례.

• docs/OPERATING.md — 상주 실행, 스케줄러와 종료 코드, 백업, 주시할 사항.

• docs/TRUST.md — 저장소 경계가 무엇이고 무엇이 아닌지, 쓰기 정책, 놓치기 쉬운 두 경계(공유 저널, 공유 모델). 비공개 저장소를 도입하기 전에 읽어라.

그것이 막는 문제를 겪기 전까지는 이상해 보이는 몇 가지 결정:

• 마시기 전에 예약. 증류기는 저널의 구간을 읽기 전에 잠금 아래에서 선점하고, 워터마크는 항상 앞으로만 이동한다. 각자 자신의 스냅샷을 다시 쓰는 두 증류기는 서로의 진행 상황을 지우고 같은 물을 수십 번 다시 마셨다.

• 워터마크는 어댑터별 단위. 추가 전용 트랜스크립트에는 바이트 오프셋, 재작성되는 아카이브에는 시퀀스 번호(재압축된 파일에 대한 바이트 오프셋은 거짓말이다).

• 에코 억제. 저장소에 이미 존재하는 인용문은 새로운 자료가 아니다 — 그것은 도구 결과를 통해 저장소가 자신을 다시 읽는 것이다. 이것이 없으면 메모리 시스템은 자신의 내용을 영원히 재발견하고 재기록한다.

• 마지막 게이트는 모델이지 사람이 아니다. 사람이 모든 초안을 승인해야 한다면, 시스템은 조용히 그 사람을 병목으로 만들고 초안은 영원히 쌓인다. 루프 안에는 항상 존재하지 않는 사람을 요구하는 것이 없어야 한다.

• kura distill run은 할 일이 없으면 2로 종료된다. 스케줄러는 "일을 했다"와 "아무것도 찾지 못했다"를 구분할 수 있어야 한다. 그렇지 않으면 워치독이 빈 큐에서 회전하며 유휴 시간이 필요한 단계를 굶긴다.

주장 대신 측정

두 질문이 하나의 숫자로 답해지고 있는데, 그래서는 안 된다.

얼마나 작아졌는가? store_ratio = 메모리와 인덱스의 토큰 / 실제로 소비된 원시 저널의 토큰. 무엇이 손실되었는가? 그것은 다른 측정이며, 백 개 중 하나의 메모리만 유지하는 저장소는 첫 번째 기준에서는 훌륭한 점수를 받으면서도 쓸모없다.

kura bench compress                       # what this store cost, from the distiller's own metrics
kura bench compress --tokenizer-command "./count-tokens"   # exact, not estimated
kura bench retention --questions bench/fixtures/questions.json

배포된 픽스처와 내장 추정기로 여기서 측정:

두 번째는 버그가 아니다. 잡담이 없는 자료에서 증류는 압축하지 않는다 — 각 메모리는 이유와 적용 방법을 추가하며, 저장소는 트랜스크립트보다 약간 커진다. 비율은 이 도구의 속성이 아니라 코퍼스의 속성이다. 그래서 여기에 헤드라인 숫자가 없고 명령이 무엇으로 계산했는지 보고하는 것이다.

유지율은 모델 없이 점수가 매겨진다: 각 심어진 사실은 회상이 반환하는 것에 반드시 나타나야 하는 마커를 지니므로, 점수는 다른 사람의 머신에서도 재현 가능하다. 방해 요소는 반전된다 — must_not_store로 표시된 사실은 저장소가 유지했다면 점수를 잃는다. 메모리 시스템은 무엇을 유지하는지만큼 무엇을 거부하는지로도 평가되기 때문이다.

score 1.0 (10/10)   decision 1/1  number 2/2  negation 1/1  reversal 1/1
                    conditional 1/1  landmine 1/1  returning 1/1  distractor 2/2

이것은 합성 픽스처에 심어진 열 개의 사실로, 로컬 Qwen3.8-27B (NVFP4)를 뇌와 서기로 사용하고 max_items = 8, coverage_passes = 2로 증류한 다음, 같은 모델을 사고자로 사용해 점수를 매긴 것이다. 다른 모델은 다른 점수를 줄 것이다: 점수는 파이프라인+모델을 측정하며, 픽스처는 모델만 변하게 하기 위해 존재한다. 그것은 사실이 찾을 수 있는지를 측정하지, 답변이 잘 읽히는지는 측정하지 않는다 — 산문을 평가하려면 모델이 필요하고, 그러면 벤치마크는 더 이상 재현 가능하지 않게 된다.

kura distill run은 배치당 한 줄을 _still/metrics.jsonl에 쓴다. 원시 측면이 여기서 나온다. 정규 측면은 증거 매니페스트가 기록된 배치를 가리키는 메모리만 계산한다 — 전체 저장소를 몇 개 배치의 원시 자료로 나누는 것은 한 자릿수 방향이 틀린 숫자이며, 이 명령의 첫 버전이 정확히 그렇게 했다. 매니페스트 이전의 메모리는 unattributed로 보고되며, 조용히 포함되지 않는다. 원시 측면은 항상 마실 때 증류기의 추정치이므로, --tokenizer-command를 사용하면 비율은 mixed로 라벨이 붙는다.

이것이 실행되는 환경

"OpenAI 호환"은 "모든 제공자"보다 좁다. 벤더의 네이티브 API는 앞에 OpenAI 호환 게이트웨이가 필요하다; 자체 URL로는 안 된다. 엄격한 서비스는 알 수 없는 최상위 필드도 거부하므로, dialect = "openai"(또는 "generic")를 설정하라 — 기본값 "vllm"은 chat_template_kwargs를 보내는데, 로컬 서버는 원하고 엄격한 서버는 400을 반환한다. 클라이언트는 일반 본문으로 한 번 재시도하고, 모든 원인을 조용한 None으로 합치지 않고 호출 실패 이유를 기록한다.

테스트

python3 -m pytest tests -q                              # 145 tests, no model required
cd dsh-plugin && npm test                               # 24 more for the plugin

게이트는 적대적으로 테스트된다: 모든 사례는 실제 모델이 게이트를 통과시키려 시도한 방식이다. test_containment.py도 같은 방식으로 작성되었다 — 모든 사례는 탈출 시도이지 행복한 경로가 아니다 — 실제였던 구멍을 지키기 때문이다: 저장소는 경로를 말할 수 있는 모든 파일에 대해 응답하곤 했다. 엔드투엔드 테스트는 실제 소켓에서 스크립트된 모델 서버에 대해 전체 증류→배수 주기를 실행한다.

라이선스

MIT.