knowl

로컬 우선. 타입 기반. 그리고 더 이상 참이 아닌 순간 은퇴합니다.

시작하기 · 대체의 원리 · 저장되는 내용 · 기능 · 에이전트 설정 · 뷰어 · 요구사항 · 전체 참조 →

코딩 에이전트는 매 세션을 빈 상태로 시작하기 때문에, 팀은 내용을 기록해 둡니다. 그리고 그 기록은 계속해서 늘어나기만 합니다. 6개월이 지나면, 저장소는 여전히 지난 봄에 마이그레이션한 데이터베이스를 보고하고 있습니다. 그 결정이 끝났다는 사실을 아무도 알려주지 않았기 때문입니다.

Knowl은 Claude Code, Cursor, Codex를 위한 세션 간 지속형 메모리입니다. 즉, MCP 메모리 서버 또는 knowl CLI를 통해 읽고 쓰는 타입 기반 지식 원자(typed knowledge atoms) — 결정, 제약, 아키텍처, 사실, 목표, 상태, 스킬 — 의 저장소로, 대체 항목이 기록될 때 이전 항목을 은퇴시키는 방식으로 동작하며, 단순히 나란히 쌓아두지 않습니다.

시작하기

Node.js 22 이상이 필요합니다.

npm install -g @dat999zx/knowl
cd your-project
knowl init

knowl init은 .knowl/ 디렉토리를 생성하고, 프로젝트 안내 파일을 설치하며, .gitignore를 업데이트하고, 감지된 에이전트(Claude Code, Codex, Cursor, Gemini CLI, Claude Desktop)에 대해 MCP 및 라이프사이클 설정을 제공합니다. 또한 로컬 임베딩 모델을 준비하지만, 해당 다운로드가 성공하지 않아도 의존하지 않습니다.

기억할 가치가 있는 것을 기록하세요:

knowl decide "Use SQLite" "Use SQLite for local project memory." \
  --reasoning "Keeps storage repository-local and simple to operate." \
  --alternatives PostgreSQL MongoDB \
  --tags database local-first

CLI 또는 연결된 에이전트에서 다시 읽어보세요:

knowl query "why sqlite"     # search project memory
knowl state                  # the active memory, as a hierarchy
knowl status                 # repository, memory, AI, and workspace status
knowl doctor                 # check setup, retrieval, and agent registration

그런 다음 새 에이전트 세션을 시작하여 호스트가 안내 및 MCP 등록을 인식하도록 하세요. CLI와 knowl_query는 동일한 저장소를 동일한 관리 규칙 하에 읽습니다.

Related MCP server: Mnemoverse Memory

아이디어: 스스로 은퇴하는 메모리

대부분의 메모리 시스템은 추가 전용(append-only)입니다. "우리는 SQLite로 전환했습니다"를 저장하면 "우리는 PostgreSQL을 사용합니다"가 여전히 활성 상태로 검색 가능하므로, 에이전트는 둘 다 가져와서 순위에 따라 선택합니다. Knowl은 동일한 주제에 대한 쓰기를 수정으로 처리합니다. 즉, 이전 항목은 superseded로 표시되고, 일반 검색에서 제외되며, knowl timeline을 통해 계속 조회할 수 있습니다.

이 단일 동작이 정확도 차이의 대부분을 설명합니다. MemoryAgentBench 충돌 해결(Conflict Resolution) 코퍼스 — 455개 사실, 현재 사실이 무엇인지에 대한 100개 질문, 상위 5개 검색, LLM 리더 없음:

동일한 코퍼스, 동일한 순위기, 동일한 쿼리 경로. 유일한 변수는 오래된 사실이 여전히 활성 상태인지 여부입니다. 이는 Knowl 자체 하네스에서의 검색 수준 측정입니다. 즉, 현재 사실이 먼저 반환되는지 여부를 묻는 것이며, 모델은 루프에 포함되지 않습니다.

벤치마크 자체 하네스에서 종단 간 검증됨

자신이 채점한 점수는 다른 사람이 채점한 점수보다 가치가 낮기 때문에, 동일한 주장이 MemoryAgentBench의 하네스 내부에서, 자체 코드로 채점되어 재실행되었습니다. Knowl이 반환한 내용을 LLM이 읽는 방식으로, 더 어렵고 완전한 종단 간 설정이며, 작업이 제공하는 가장 큰 컨텍스트에서 수행되었습니다:

18,332개의 사실, 100개의 질문, 부분 문자열 정확 일치. 모든 행은 gpt-4o-mini를 리더로 사용하며, Knowl도 포함됩니다. 논문은 모든 RAG 및 메모리 에이전트에 대해 이를 명시하므로, 동등 비교입니다. Knowl의 수치는 여기서 측정되었으며, 다른 모든 수치는 MemoryAgentBench 논문의 표 2에서 가져왔습니다. 논문이 이 작업에 대해 평가하지 않은 시스템은 나열되지 않습니다.

동일한 하네스에서 대체 기능을 끄면 Knowl은 73으로 떨어지며, 그 차이는 코퍼스 크기가 40배 변해도 유지됩니다:

두 섹션은 서로 다른 것을 측정하므로 비교할 수 없습니다: 98%는 리더 없이 6K에서의 검색 상위 1, 90은 리더와 함께 262K에서의 종단 간 정확도입니다. 두 번째만 위에 게시된 시스템과 비교할 수 있습니다. 프로토콜, 체크인된 결과, 그리고 작업이 다루지 않는 내용(Knowl이 14점 검색 상한 대비 7점을 기록한 다중 홉 포함)은 벤치마크를 참조하세요.

대체는 수정이지 삭제가 아닙니다. 항목, 그 주장, 그리고 그 이력은 모두 유지됩니다.

모의 실험이 아닙니다 — 게시된 CLI에 대해 동일한 시퀀스를 demo.tape에서 녹화한 것입니다:

저장되는 내용

모든 원자는 정확히 일곱 가지 범주 중 하나를 가집니다:

내용과 함께, 각 원자는 상태(active, deprecated, rejected, archived, superseded), 신선도 플래그, 신뢰도, 태그, 소스 커밋, 영향받는 경로, 그리고 선택적 증거(evidence) (파일, 커밋, 테스트, 명령, URL, 인덱싱된 코드 심볼을 가리킴)를 유지합니다. 파일 및 심볼 증거는 코드가 이동할 때 자체적으로 만료되며, 이는 원자가 더 이상 존재하지 않는 저장소 버전을 주장하는 대신 최신 상태가 아닐 수 있음을 인정하는 방식입니다.

Knowl이 의도적으로 저장하지 않는 것은 대화 내용입니다. 라이프사이클 캡처는 제한된 이벤트와 요약만 기록합니다. 프롬프트, 대화록, stdout, 환경 변수는 절대 기록하지 않습니다. 원시 대화록 검색은 호스트가 이미 작성한 파일에 대한 옵트인, 기본 꺼짐 인덱스로 존재합니다.

→ 지식 모델 참조

에이전트 연결

knowl serve는 stdio MCP를 통해 저장소를 노출합니다. knowl init이 이를 자동으로 등록해 줍니다. 설치된 가이드라인이 에이전트에게 요청하는 워크플로는 간단합니다:

1. 저장소 파일을 읽기 전에 주제를 명명하는 단어로 메모리를 질의합니다.

2. 활성 적중 결과를 직접 사용합니다. 누락, 충돌 또는 오래된 결과가 있는 경우에만 파일을 검사합니다.

3. 진행하면서 지속 가능한 발견, 명시된 목표, 반복되는 진단을 저장하고, 모순된 메모리는 복제하지 않고 수정합니다.

실제로는 이렇게 보입니다 — 새로운 세션, 컨텍스트 없음, 붙여넣은 내용 없음:

You     why did we pick SQLite over Postgres?

Agent   → knowl_query "sqlite postgres database choice"
        ← decision · Use SQLite · active · fresh
          "Keeps storage repository-local and simple to operate."
          alternatives: PostgreSQL, MongoDB
          tags: database, local-first

        SQLite keeps the store repository-local and simple to operate.
        Postgres and MongoDB were both considered and rejected on that
        basis.

에이전트는 단일 파일도 열기 전에 답변했으며, 사용자가 거부한 옵션까지 알고 있었습니다 — 코드는 이를 알려줄 수 없습니다. 거부된 대안은 코드베이스에 흔적을 남기지 않기 때문입니다.

훅을 사용할 수 있는 곳에서는 훅이 세션 수명 주기를 소유합니다: 부트스트랩 컨텍스트, 캡처, 체크포인트, 최종화가 에이전트에게 요청 없이 이루어집니다. 훅을 사용할 수 없는 곳에서는 knowl task run, task start, task checkpoint, task finish가 동일한 작업을 수동으로 처리합니다.

knowl init은 감지된 모든 호스트에 대해 MCP 등록을 작성합니다. 수동으로 연결하려면 항목은 모든 곳에서 동일합니다:

{
  "mcpServers": {
    "knowl": { "command": "knowl", "args": ["serve"] }
  }
}

Windows에서는 명령어로 knowl.cmd를 사용하세요. Codex는 mcp_servers 아래에서 동일한 항목을 읽습니다.

→ MCP 도구 및 리소스 · 수명 주기 참조

Knowl의 용도

Knowl은 한 가지 작업을 수행합니다: 작업 중인 에이전트를 위해 저장소의 엔지니어링 진실을 정확하게 유지하는 것입니다. 사용자 선호도, 채팅 기록이 아닌 — 코드베이스의 결정, 제약 조건, 아키텍처, 그리고 그중 현재도 유효한 것이 무엇인지입니다.

그로부터 세 가지 선택이 따릅니다:

• 자유 텍스트가 아닌, 유형화됨. 결정은 추론과 사용자가 거부한 대안을 담습니다. 제약 조건은 계속 유지되어야 하는 규칙입니다. state 원자는 예상대로 구식이 됩니다. 검색은 이러한 차이점을 기준으로 순위를 매길 수 있습니다. 메모 파일의 단락을 기준으로 순위를 매길 수는 없습니다.

• 추가 전용이 아닌, 관리됨. 상태, 신선도, 출처, 충돌 식별, 대체를 통해 저장소는 어떤 것이 더 이상 참이 아니라고 알려줄 수 있습니다. 이것이 메모리와 계속 쌓여가는 메모 더미의 전체 차이점입니다.

• 서비스가 아닌, 저장소 로컬. 데이터베이스는 설명하는 코드 옆에 위치합니다. 계정, 외부 전송, 사용자와 프로젝트 기록 사이의 공급업체가 없습니다.

Knowl은 의도적으로 개인화 계층이 아닙니다. 사용자에 대한 의견이 없으며, 자체 대화록을 보관하지 않습니다.

기능

아래의 모든 기능은 CLI와 MCP에 연결된 모든 에이전트에서 동일한 로컬 데이터베이스에 대해 작동합니다. 계정, 서버, API 키가 필요 없습니다. 각 항목은 세부 사항과 제한 사항에 대해 전체 참조로 연결됩니다.

♻️ 스스로 수정하는 지식

일곱 가지 유형화된 원자 유형으로, 동일 주제에 대한 쓰기는 이전 항목 옆에 두지 않고 은퇴시킵니다. 이 하나의 동작이 90 대 73의 차이입니다. 파일이나 심볼에 첨부된 증거는 코드가 이동하면 자동으로 구식이 됩니다.

conflicts · timeline · query --as-of · pr --since · index-code

🎯 에이전트에 맞춘 검색

벡터 우선 순위에 제한된 BM25 폴백을 사용하며, 신선도, 상태, 신뢰도로 재순위화되어 단순히 유사한 답변이 아닌 현재 답변이 승리합니다. 임베딩 모델은 로컬이며 선택 사항입니다. 없어도 키워드 검색이 가능하며, 어떤 것도 머신을 떠나지 않습니다.

query · context --token-budget · config set-model · access

⏱️ 세션을 넘어 지속되는 작업

Claude Code, Codex, Cursor에서 훅은 에이전트에게 요청 없이 부트스트랩, 캡처, 체크포인트, 최종화를 처리합니다. 깔끔한 마무리는 최대 8개의 지속 가능한 후보를 추출합니다. 키 아래에 작업 스트림을 보관하고 모든 세션, 모든 디렉토리에서 다시 가져옵니다.

task run · handoff · park · resume <key>

🔗 워크스페이스

API 저장소가 프론트엔드 저장소에 필요한 것을 배웠습니다. 연결하면 질의가 확장되며, 각 저장소는 자체 데이터베이스와 소유권 경계를 유지합니다. 공유된 피어 원자를 ID로 전체 열거나, 호출 시 이름을 지정하여 해당 저장소의 작업을 여기서 완료합니다. 저장소가 이미 보유한 지식은 승격할 때만 공유됩니다.

workspace init · workspace add · workspace promote --apply

📦 재사용 가능한 절차

.knowl/skills/ 아래에 스크립트와 함께 절차를 패키징한 다음, 실행되기 전에 읽습니다. 여러 원자를 AI 제공자 없이 결정론적으로 하나의 아키텍처 요약으로 통합합니다.

skill list · skill read · skill run · synthesize

💾 사용자 데이터와 복구

체크섬이 있는 JSONL 내보내기 및 가져오기로, 동일한 원자가 두 곳에서 변경된 경우를 위한 네 가지 명시적 정책을 제공합니다. 복원은 먼저 스키마, 크기, SHA-256, SQLite 무결성을 확인한 후에만 작업을 수행하며, 먼저 복원 전 스냅샷을 생성합니다.

export · import --on-divergence · snapshot create · gc · doctor

첫날 알아두면 좋은 명령어:

knowl query "auth design"              # search project memory
knowl state                            # the active memory, as a hierarchy
knowl conflicts                        # items that contradict each other
knowl timeline <item-id>               # every version an atom ever had
knowl context --token-budget 1500      # a fixed-size briefing for an agent
knowl pr --since origin/main           # knowledge your diff may invalidate
knowl doctor                           # setup, retrieval, and registration

• 일곱 가지 원자 유형 — 위에 나열됨. 하나의 커지는 메모 파일 대신 구조화됨.

• 자동 대체 — 동일 주제에 대한 쓰기는 이전 항목을 은퇴시킵니다. 이것이 위의 90 대 73 차이입니다.

• 충돌 식별 — 원자를 배타적으로 표시하면 Knowl은 동일한 질문에 대한 두 번째 활성 답변을 조용히 보유하는 대신 거부합니다. knowl conflicts

• 전체 기록 — 원자가 가졌던 모든 버전은 불변 어설션으로 유지됩니다. knowl timeline <item-id>

• 시간 여행 — 과거 날짜에 프로젝트가 믿었던 것을 질의: knowl query "auth design" --as-of 2026-01-01T00:00:00Z

• 증거 — 파일, 심볼, 커밋, 테스트, 명령어 또는 URL을 원자에 첨부합니다. 파일 및 심볼 증거는 코드가 이동하면 자동으로 구식이 됩니다.

• 드리프트 감지 — knowl pr --since origin/main은 병합하기 전에 diff가 무효화했을 수 있는 지식을 플래그 지정합니다.

• 코드 인텔리전스 — .ts / .tsx / .js / .jsx에 대한 증분 Tree-sitter 인덱스로, 증거가 줄 번호뿐만 아니라 symbol:// 로케이터를 가리킬 수 있습니다. knowl index-code

• 비밀 안전 쓰기 — 모든 쓰기는 저장되기 전에 감지된 비밀, 민감한 경로, 과도한 콘텐츠를 검사합니다. 장기 메모리는 자격 증명이 있어서는 안 되는 마지막 장소입니다.

→ 지식 모델 · 증거 및 드리프트

• 벡터 우선 순위에 제한된 BM25 폴백을 사용하며, 신선도, 상태, 신뢰도, 최신성으로 재순위화되어 단순히 유사한 답변이 아닌 현재 답변이 승리합니다. (이것은 에이전트/MCP 경로입니다. CLI에서 단일 저장소 knowl query는 어휘 기반입니다.)

• 오프라인에서 실행. 임베딩 모델은 로컬이며 선택 사항입니다. 없어도 키워드 검색이 가능합니다. 검색은 질의를 어디로도 보내지 않습니다.

• 다섯 가지 번들 임베딩 사전 설정, 200개 이상의 언어를 지원하는 다국어 설정 포함, 사용자 정의 ONNX 모델을 위한 custom도 있습니다. knowl config set-model <model>

• 정확한 식별자 지원 — 파일 이름, 항목 ID, symbol:// 로케이터는 의미적 유사성이 약할 때도 여전히 적중합니다.

• 토큰 예산 컨텍스트 팩 — 제약 조건이 먼저 고정된 고정 크기 브리핑을 에이전트에 전달하여, 양보할 수 없는 규칙이 잘려나가지 않도록 합니다: knowl context --query "auth rollout" --token-budget 1500

• 사용 피드백 — 에이전트가 결과가 도움이 되었는지 보고하고, knowl access는 많이 사용되는 것, 오래된 것, 계속 수정을 유발하는 것을 보여줍니다.

→ 검색 및 컨텍스트

• Claude Code, Codex, Cursor에서 자동 수명 주기 — 부트스트랩, 캡처, 체크포인트, 최종화가 에이전트에게 요청 없이 훅을 통해 이루어집니다.

• 그 외 모든 것을 위한 작업 루프 — knowl task start, checkpoint, finish 또는 단일 명령어를 knowl task run "Run tests" -- npm test로 래핑합니다.

• 세션 종료 시 승격 — 깔끔한 마무리는 세션에서 최대 8개의 지속 가능한 후보를 추출하고, 세 번 성공한 명령어는 이를 설명하는 skill 원자가 됩니다.

• 핸드오프 — 이 저장소의 다음 세션을 위해 하나의 배턴을 남깁니다. 한 번 전달된 후 보관됩니다.

• 재개 키 — 유지하는 짧은 키 아래에 작업 스트림을 보관하고, 모든 세션, 모든 디렉토리에서 나중에 여러 번 다시 가져옵니다. knowl resume <key>

• 선택적 대화록 검색 — 기본적으로 꺼져 있으며, 꺼져 있으면 디스크에 아무것도 존재하지 않습니다. 켜면 과거 세션의 산문을 검색할 수 있게 되어, 메모리 누락이 기억 상실 대신 느린 조회로 이어집니다.

→ 작업, 세션 및 수명 주기

API 저장소가 프론트엔드 저장소에 필요한 것을 배웠습니다. 연결하면 질의가 확장되며, 각 저장소는 자체 데이터베이스와 소유권 경계를 유지합니다.

knowl workspace init product      # create the workspace
knowl workspace add product       # run inside each repo that joins it
                                  # ...or --default-visibility repo to keep its writes private

knowl workspace promote                               # pick what to share from a list
knowl workspace promote --category decision --apply   # or name it outright

워크스페이스에 가입하면 저장소가 그때부터 쓰는 내용을 공유하며, 공유할 때 이를 알립니다. --default-visibility repo를 전달하여 거부할 수 있습니다. 저장소가 이미 알고 있는 내용은 승격할 때만 공유됩니다. 피어 결과는 이를 소유한 저장소로 레이블이 지정되며, 공유된 결과는 ID로 전체 열 수 있습니다. 단, affectedPaths나 증거는 사용자가 위치하지 않은 체크아웃에 대해 확인되므로 제외됩니다. 누락되었거나 읽을 수 없는 피어는 건너뛰고 공개되며, 로컬 검색이 실패하는 이유가 되지 않습니다.

형제 저장소에 쓰는 것은 우연이 아니라 의도적입니다. 에이전트가 호출 시 저장소를 명명하고, 해당 호출은 그 저장소로 실행됩니다 — 해당 저장소의 저장소, 구성, 소유권 규칙, 자체로 스탬프됨 — 정확히 CLI에서 cd가 항상 작동했던 방식입니다. 아무것도 명명하지 않으면 외부 ID는 이전과 같이 거부됩니다. 어느 쪽이든 저장소의 비공개 지식은 승격될 때까지 비공개로 유지됩니다.

→ 워크스페이스

• 파일 기반 스킬 — 절차와 스크립트를 .knowl/skills/ 아래에 패키징한 후, 실행 전에 검사할 수 있습니다. knowl skill list · read · run

• 결정론적 합성 — AI 제공자 없이 여러 원자를 하나의 아키텍처 요약으로 통합: knowl synthesize --scope storage

→ 스킬 및 합성

• 이식 가능한 내보내기/가져오기 — 체크섬이 포함된 JSONL, 동일한 원자가 두 곳에서 변경된 경우를 위한 네 가지 명시적 발산 정책. knowl export · knowl import --on-divergence newer

• 검증된 스냅샷 — knowl snapshot create는 체크섬 매니페스트를 작성합니다. 복원 시 스키마 버전, 크기, SHA-256, SQLite 무결성을 아무것도 건드리기 전에 검증하고, 먼저 사전 복원 스냅샷을 생성합니다.

• 가비지 컬렉션 — 기본적으로 미리보기를 제공하고 최근 사용된 항목을 보호합니다. knowl gc

• knowl doctor — 설정, 구성, 무결성, 스키마, 검색, 벡터 커버리지, 에이전트 등록, 작업 공간 상태를 확인하는 단일 명령어.

• 선택적 AI — knowl ask 및 원시 텍스트 수집을 위한 제공자를 구성합니다. 위의 모든 기능은 AI 없이도 작동합니다.

→ 이식성 및 유지보수 · 선택적 AI

로컬 뷰어 살펴보기

knowl view는 실행 시마다 새로운 액세스 토큰을 사용하여 127.0.0.1에서 읽기 전용 검사기를 시작합니다. 포트를 안다고 해서 데이터를 읽을 수 있는 것은 아닙니다.

knowl view

검색, 카테고리별 필터링, 오래된 링 감지, 특정 영역 집중, 원자 클릭 시 증거와 타임라인 확인. 그래프는 공유 태그와 카테고리 기반 엣지를 통해 원자를 연결합니다. 이는 인과 관계나 증거 그래프가 아닌 탐색 보조 도구입니다. 모든 상태의 전체 로컬 콘텐츠를 표시하므로, 루프백 바인딩이 개인정보 보호 경계입니다. 공용 프록시나 터널 뒤에 두지 마십시오.

→ 로컬 뷰어

그 외 모든 것

27개의 MCP 도구 (트랜스크립트 검색이 켜져 있으면 +3, 클라우드 작업 공간에 연결 시 +1, 로컬 작업 공간에 연결 시 +1, 변경 영향이 켜져 있으면 +1)

그리고 두 개의 리소스 URI · 완전한 CLI, knowl status부터 knowl audit까지 · 읽기 전용 무결성 감사 · 체크인된 거버넌스 및 500개 케이스 회귀 테스트 스위트에 대해 knowl eval로 직접 실행할 수 있는 검색 평가.

→ CLI 참조 · MCP 도구 · 벤치마크

요구 사항 및 로컬 데이터

Node.js 22 이상. Knowl이 프로젝트에 기록하는 모든 것은 .knowl/ 아래에 저장되며, knowl init이 이를 .gitignore에 추가합니다:

작업 공간 매니페스트는 멤버 저장소 외부에 위치합니다. 체크아웃 경로가 머신 로컬이기 때문입니다. 내보내기와 스냅샷은 사용자가 요청할 때만 기록됩니다.

문서

위의 내용이 요약입니다. **전체 참조**는 모든 하위 시스템을 깊이 있게 다루는 하나의 문서입니다. 의도적으로 제한된 부분도 포함되어 있으며, 이는 일반적으로 실제로 알아야 할 내용입니다.

기여

설정, 풀 리퀘스트 전 실행해야 할 검사, 이 코드베이스가 따르는 규칙은 CONTRIBUTING.md를 참조하세요. 기여자는 첫 번째 풀 리퀘스트에서 기여자 라이선스 동의서에 한 번 동의해야 합니다.

라이선스

Knowl은 Apache License 2.0에 따라 라이선스가 부여됩니다. Apache-2.0은 상표권을 부여하지 않습니다.