The Library of Context

AI 컨텍스트를 위한 가상 메모리: 모델 외부에서는 영속적이고, 모델 내부에서는 제한적입니다.

AI 모델은 유한한 네이티브 컨텍스트 창을 가집니다. 긴 대화는 결국 확장되어 오래된 정보가 잘리거나 압축됩니다. 컨텍스트 거버너를 통해 라우팅되는 호출의 경우, Library는 각 기록된 이벤트를 SQLite에 저장하고 보호된 이벤트, 최근 이벤트, 검색된 레코드에서 제한된 모델 요청을 조립합니다.

모델의 컨텍스트 창을 독서대로 생각해 보세요. Library는 책상보다 훨씬 많은 책을 보관할 수 있지만, 사서는 현재 작업에 필요한 책만 책상에 펼쳐 놓습니다. 작업이 바뀌면 책상 위의 책도 교체됩니다. 책이 더 쌓이지는 않습니다.

[!IMPORTANT] 이 프로젝트는 모델의 물리적 컨텍스트 창 한도를 확장하는 것이 아니라 주소 지정 가능한 컨텍스트를 확장합니다. 프로덕션용 멀티 테넌트 메모리 서비스가 아닌 로컬 프로토타입과 협업을 위한 것입니다. 명시적인 지원 범위는 Capability Status를 참조하세요.

일반적인 압축과 다른 점

기존 압축은 커지는 대화 기록을 더 작고 손실 있는 연속체로 바꾸며, 원본 세부 정보가 활성 워크플로우 밖에 남을 수 있습니다. Library는 되돌릴 수 있는 의미론적 페이징을 사용합니다:

traditional:  growing transcript -> compacted transcript -> continue

Library:      durable event log -> bounded recent/protected context
                       |                    + relevant retrieved books
                       +-----------> fresh model request on every turn

원본 이벤트는 검사하고 복구할 수 있습니다. 요약은 탐색 보조 도구가 될 수 있지만, 유일하게 남는 사본일 필요는 없습니다.

related-work landscape는 이 설계를 모델 장기 컨텍스트 방법, 검색, 프롬프트 압축, 제공자 압축, 에이전트 메모리, 체크포인팅, 추론 런타임 페이징과 비교합니다. 여기서 "압축"은 원본이 다른 계층에서 보존되지 않는 한 독립적으로 주소 지정할 수 없는, 더 작고 잠재적으로 손실 있는 연속 표현을 의미합니다.

Related MCP server: local-memory-mcp

기능

• 컨텍스트 거버너: prepare -> model call -> commit 수명 주기 작업.

• 영속적인 SQLite 스레드 이벤트와 트랜잭션 인덱싱 아웃박스.

• 즉각적인 자체 컨텍스트 읽기 동작을 위한 토큰 목표 기반, 이벤트 수 제한 최근 링; 과대 이벤트는 디스크가 아닌 모델 엔벨로프에서만 잘립니다.

• 오버플로 및 재시작 복구를 위한 영속적인 SQLite 아웃박스를 갖춘 제한된 작업 링.

• 지침, 결정, 활성 계획, 미해결 상태를 위한 보호된 컨텍스트.

• 큐 상태를 포함한 기록, 임베딩, 인덱싱된 워터마크.

• 대화 기록 증가를 대체하는 신선하고 제한된 프롬프트 엔벨로프.

• 하이브리드 벡터, SQLite FTS5, 중요도, 최신성 검색.

• 바이트 제한 프로세스 RAM과 선택적 일회용 로컬 Redis 핫 계층.

• 독서대 스왑 보고서: swapped_in, swapped_out, retained.

• Python, 로컬 HTTP, CLI, STDIO MCP 통합 인터페이스.

• 의존성 없는 해싱 임베딩과 선택적 로컬 Ollama 어댑터.

에이전트 또는 모델 게이트웨이가 모든 턴을 거버너를 통해 라우팅하면 거버너는 자동으로 작동합니다. MCP 전용 통합은 협력적입니다: 호스트는 선반 및 독서대 도구를 사용할 수 있지만, 이미 도구를 호출한 모델 요청을 다시 쓰거나 문서화되지 않은 내부 압축 훅을 대체할 수는 없습니다.

아키텍처 개요

flowchart LR
    U[User or tool event] --> A[Durable SQLite append]
    A --> E[(Thread event log)]
    A --> O[(Transactional outbox)]
    A --> R[Recent context ring]
    O --> W[Bounded work ring]
    W --> I[Embed and index workers]
    I --> S[(SQLite library and FTS)]
    I --> C[RAM and optional Redis cache]
    R --> G[Context governor]
    S --> G
    P[Protected context] --> G
    G --> D[Bounded reading desk]
    D --> M[Native model context]
    M --> X[Assistant response]
    X --> A

빠른 시작

기본 구성에는 Python 3.11 이상만 필요합니다. Redis는 선택 사항입니다.

Windows PowerShell에서:

git clone https://github.com/hwillGIT/library-of-context.git
cd library-of-context
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m library_of_context quickstart

macOS 또는 Linux에서:

git clone https://github.com/hwillGIT/library-of-context.git
cd library-of-context
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m library_of_context quickstart

빠른 시작은 임시 데이터베이스로 보호, 프롬프트 조립, 이벤트 기록, 인덱싱, 정리를 실행합니다. Redis, Docker, 클라우드 서비스, 모델 API를 사용하지 않습니다. 설치 가이드로 계속 진행하세요.

이미 실행 중인 에이전트에 추가

Codex, Python, HTTP 구성 예제는 Add the Library to your agent를 참조하세요. MCP 서버 구성 후 클라이언트를 다시 시작하거나 별도 세션을 시작하세요. 구성은 이미 진행 중인 채팅에는 영향을 미치지 않습니다.

자동 관리되는 Python 텍스트 에이전트 실행

from library_of_context import GovernedTextAgent, LibraryOfContext


def call_my_model(messages: list[dict[str, str]]) -> str:
    return my_model_client.generate(messages=messages)


with LibraryOfContext("data/library.sqlite", redis_url="") as library:
    with library.open_context_governor(
        "agent-thread-42",
        token_budget=12_000,
        recent_token_budget=4_000,
        protected_token_budget=2_000,
    ) as context:
        context.protect(
            "Production changes require a canary wave.",
            label="deployment-policy",
        )

        agent = GovernedTextAgent(
            context,
            call_my_model,
            system_prompt="Work carefully and cite retrieved project evidence.",
        )
        response = agent.turn(
            "Diagnose the deployment failure.",
            turn_id="request-0001",
        )
        context.flush(timeout=5)
        print(context.status()["watermarks"])

콜백은 제공된 messages를 정확히 그대로 전송해야 합니다. 다른 대화 기록을 추가하거나 제공자 관리 대화를 계속해서는 안 됩니다. 내장 어댑터는 텍스트 전용입니다. 구조화된 도구 호출, 스트림, 첨부 파일, 멀티모달 콘텐츠에는 사용자 정의 직렬화 어댑터가 필요합니다.

전체 프로토콜은 Context Governor를 참조하세요.

MCP 통합

일반 MCP 에이전트의 경우 integrations/README.md의 프로젝트 격리 템플릿과 병합 준비 완료 에이전트 지침을 사용하세요. 이는 협력적 메모리이며 호스트의 네이티브 대화 기록을 제어하지 않습니다.

로컬 STDIO 서버는 다음으로 검사할 수 있습니다:

python -m library_of_context.mcp_server --no-redis

모델 호출 경계를 소유한 사용자 정의 MCP 게이트웨이는 다음을 사용할 수 있습니다:

Library는 선반, 검색, 독서대, 무상태 세션, 거버너 도구를 노출합니다. 게이트웨이 전용 도구는 반환된 messages를 완전한 다음 모델 요청으로 전송하는 호스트에서만 활성화하세요.

로컬 HTTP API

python -m library_of_context --no-redis serve

거버너 엔드포인트:

/books, /library/ingest, /catalog/query, /desk/* 라우트는 하위 수준 라이브러리를 노출합니다. 서버는 루프백에 바인딩되며 인증이 없습니다. 다른 머신에 직접 노출하지 마세요.

스토리지 계층

1. 최근 링: 스레드별 순서 이벤트, 이벤트 수와 예상 토큰 목표로 제한. 신선한 컨텍스트가 보이도록 과대 이벤트 하나는 상주할 수 있습니다. 프롬프트 조립은 모델에 보이는 뷰를 하드 엔벨로프 예산으로 자릅니다. 이는 LRU가 아닙니다. 대화 순서가 중요합니다.

2. 프로세스 RAM: 핫 북과 검색 결과를 위한 바이트 제한 LRU.

3. 로컬 Redis: 핫 북, 쿼리, 독서대, TTL, 무효화 세대를 위한 선택적 공유 캐시.

4. SQLite: 이벤트, 아웃박스, 텍스트, 메타데이터, FTS, 벡터 저장소의 원본.

Redis는 일회용입니다. 기본 로컬 Redis 구성은 영속적인 메시지 브로커가 아니며 팀 이벤트 스트림으로 사용해서는 안 됩니다.

Windows에서 무료 로컬 Redis

Docker와 클라우드 계정은 필요하지 않습니다. 포함된 PowerShell 스크립트는 Ubuntu WSL 내부에 Redis 서비스를 설치합니다. WSL 2, Ubuntu 배포판, systemd가 필요합니다:

powershell -ExecutionPolicy Bypass -File .\scripts\install-local-redis.ps1
.\.venv\Scripts\python.exe -m library_of_context --db data/redis-check.sqlite doctor

doctor는 스토리지 계층을 확인하면서 구성된 SQLite 데이터베이스를 엽니다. 위 예제는 data/redis-check.sqlite를 생성합니다.

SQLite와 프로세스 RAM으로 충분하다면 모든 곳에서 --no-redis를 사용하세요.

성능 한도

프롬프트 조립은 제한되며 기록된 이벤트는 트랜잭션 아웃박스를 사용합니다. FTS는 제한된 후보 집합을 반환하고, 벡터 검색은 네임스페이스의 모든 활성 레코드를 정확히 점수 계산합니다. 따라서 대규모 카탈로그 확장성 주장은 측정된 증거가 필요하며, 정확 경로가 선언된 한도를 초과할 때는 제한된 벡터 검색 어댑터가 필요합니다.

Performance and Scaling은 측정, SLO 기준, 벤치마크 질문을 정의합니다. Why These Improvements?는 더 단순한 대안, 도입 트리거, 증거 게이트를 비교하며, Roadmap은 조건부 작업을 순서대로 나열합니다.

문서

설계 방향을 함께 만들기

열린 설계 질문에는 다음이 포함됩니다:

• 어떤 컨텍스트가 자동으로 보호되어야 하며, 누가 보호를 해제할 수 있을까요?

• 문서 QA가 아닌 에이전트 스레드의 검색 품질은 어떻게 측정해야 할까요?

• 100,000~1,000,000개 청크에 적합한 로컬 ANN 어댑터는 무엇일까요?

• 브랜치는 컨텍스트를 어떻게 상속, 대체, 병합해야 할까요?

• 비공개 스레드에서 팀 카탈로그로 승격하기에 안전하고 유용한 지식은 무엇일까요?

• 공유 이벤트 플레인은 Redis Streams, NATS JetStream 또는 다른 브로커를 사용해야 할까요?

• ACL 해지가 클라우드를 프롬프트 중요 경로에 두지 않고 로컬 캐시를 무효화하려면 어떻게 해야 할까요?

• 서로 다른 모델 토크나이저에서 사용자에게 예측 가능하게 느껴지는 토큰 압력 정책은 무엇일까요?

더 자세한 목록은 ROADMAP.md에 있습니다. 질문, 벤치마크 결과, 설계 노트, 어댑터, 실패 테스트, 비평을 환영합니다.

기여

CONTRIBUTING.md를 읽고, 연구 질문이나 설계 제안을 열고, 풀 리퀘스트는 초점을 유지하세요. 이 프로젝트는 특히 재현 가능한 검색 벤치마크, ANN 어댑터, 토크나이저 통합, 개인정보 보호 검토, 큐 및 크래시 테스트, 에이전트 프레임워크 게이트웨이를 환영합니다.

라이선스

MIT © Library of Context 기여자.