AI 튜토리얼

loci로 견고하고 타입이 지정된 AI 에이전트 메모리 구축

loci 설치 방법, 지속적인 사용자 사실의 저장 및 검색, 순위가 매겨진 메모리의 프롬프트 주입 방법과 MCP, Hermes, 직접 Python 통합 중 선택하는 방법을 알아보세요.

2026년 10월 2일약 9분 소요

loci란 무엇인가요?

loci는 AI 에이전트를 위한 타입이 지정된 장기 메모리 계층입니다. 대화에서 오래 유지할 가치가 있는 사실을 추출하고, 이를 SQLite에 저장하며, 나중에 회상할 수 있도록 순위를 매기고, 더 이상 유용하지 않은 정보는 제거합니다.

이 프로젝트는 메모리에 장소와 구조가 모두 필요하다는 생각을 바탕으로 합니다. 저장된 모든 문장을 동일하게 취급하는 대신, loci는 선호도, 기한, 목표, 관계 및 기타 정보 유형을 구분하여 각각 적절한 수명 주기를 따를 수 있도록 합니다.

loci는 Lima가 프로덕션에서 사용하는 메모리 시스템을 포팅한 뒤, 특정 호스트 애플리케이션에 종속되지 않도록 다시 작성한 프로젝트입니다.

메모리 시스템 작동 방식

타입이 지정된 메모리

모든 메모리는 다음 8개 카테고리 중 하나에 속합니다.

routine
study
preferences
finance
goals
relationships
constraints
ephemeral

메모리에는 4개의 중요도 등급과 상태 수명 주기도 적용됩니다. 이 구조를 통해 시스템은 지속적인 선호도와 일시적인 기한 또는 짧게 유지되는 사실을 서로 다르게 처리할 수 있습니다.

두 가지 추출 경로

추출은 두 가지 메커니즘을 결합합니다. 모델 기반 추출기는 대화의 의미를 분석하고, 정규 표현식 휴리스틱은 명시적으로 지원되는 표현을 감지합니다. 결과를 병합할 때는 모델의 출력이 우선합니다.

모델 제공업체를 사용할 수 없을 때에도 정규 표현식 경로는 계속 실행될 수 있습니다. 모델 호출, 제공업체 SDK 및 API 키는 의도적으로 호스트 애플리케이션에 맡기며, 호스트 애플리케이션은 ModelExtractor를 주입할 수 있습니다.

필터링, 순위 지정 및 감쇠

쓰기 필터는 일시적인 기분이나 이와 유사한 단기적 발언이 영구적인 프로필 데이터가 되는 것을 방지합니다. 예를 들어 “오늘은 피곤하다”라는 말은 몇 시간 동안은 사실일 수 있지만 몇 달 후에는 오해를 불러일으킬 수 있습니다.

메모리를 모델 컨텍스트에 추가할 때 loci는 결과를 12개의 사실로 제한합니다. 중요도를 기준으로 순위를 매긴 다음, 기한까지 남은 시간과 최신성을 고려합니다. 이 제한은 프롬프트가 한없이 커지는 것을 방지합니다.

매일 수행되는 통합 및 감쇠 작업은 저장소를 유용하게 유지합니다.

완전히 동일한 중복 항목은 병합됩니다.
확인되지 않은 추측은 시간이 지나면 만료됩니다.
임시 사실의 TTL은 24시간입니다.
완료된 목표는 90일 후 만료됩니다.

통합 방식 선택

loci는 하나의 공유 코어와 두 개의 어댑터를 제공합니다.

MCP 서버

MCP 어댑터는 호환되는 모든 MCP 클라이언트에서 작동합니다. 이 어댑터는 remember, recall, forget의 세 가지 도구를 제공합니다.

MCP는 요청과 응답을 기반으로 하므로 턴 종료 시 자동으로 실행되는 훅이 없습니다. 에이전트가 remember를 명시적으로 호출해야 합니다. 요청에 따라 메모리를 회상하여 컨텍스트에 주입할 수 있습니다.

Hermes 플러그인

Hermes 어댑터는 동일한 세 가지 도구를 제공하지만, 자동 추출도 지원하고 모든 호출 전에 컨텍스트를 주입합니다. Hermes가 모델 응답 후 대화를 검사할 수 있는 post_llm_call 훅을 제공하기 때문에 가능합니다.

Python 직접 통합

에이전트 루프를 직접 제어하고 추출, 저장, 회상 및 컨텍스트 주입이 수행되는 시점을 결정하려면 코어 라이브러리를 직접 사용하세요.

설치 및 설정

코어 패키지 설치

pip install mowave-loci

MCP 지원 설치

pip install mowave-loci[mcp]

MCP 추가 기능을 설치한 후 MCP 클라이언트 설정에 loci를 추가합니다.

{
  "mcpServers": {
    "loci": {
      "command": "python",
      "args": ["-m", "loci.adapters.mcp_server.server"]
    }
  }
}

클라이언트를 다시 시작하거나 새로 고침하여 remember, recall, forget 도구를 인식하도록 합니다.

Hermes 플러그인 설치

hermes plugins install <you>/loci
hermes plugins enable loci

<you>/loci를 설치 환경에 맞는 플러그인 저장소 또는 소스로 바꿉니다.

저장소 설정

기본적으로 loci는 ~/.loci/memory.db의 SQLite 데이터베이스에 메모리를 저장합니다. 다른 파일을 사용하려면 LOCI_DB 환경 변수를 설정하세요.

export LOCI_DB=/path/to/memory.db

별도의 데이터베이스 서버는 필요하지 않습니다.

Python 기본 사용법

핵심 작업 흐름은 저장소를 만들고, 후보 메모리를 추출하고, 필터링한 다음, 승인된 메모리를 저장하고, 활성 메모리를 시스템 프롬프트에 추가하는 것입니다.

from loci import Store, extract, should_persist, context_block

store = Store()

for memory in extract(
    "eu prefiro respostas curtas",
    assistant_text=reply,
):
    if should_persist(memory):
        store.upsert(memory)

system_prompt += "\n\n" + context_block(store.active())

이 예제에서 reply는 대화에 연결된 어시스턴트의 텍스트를 나타냅니다. 포르투갈어로 된 사용자 메시지는 사용자가 짧은 답변을 선호한다는 의미입니다.

Store()는 설정된 SQLite 메모리 저장소를 엽니다.
extract(...)는 대화에서 후보 메모리를 생성합니다.
should_persist(memory)는 쓰기 필터를 적용합니다.
store.upsert(memory)는 승인된 메모리를 삽입하거나 업데이트합니다.
store.active()는 활성 메모리를 가져옵니다.
context_block(...)는 프롬프트 주입을 위해 해당 메모리를 형식화합니다.

MCP 도구 사용

MCP 서버를 설정하면 연결된 에이전트가 다음 세 가지 작업을 사용할 수 있습니다.

remember: 유지해야 하는 사실을 의도적으로 저장합니다.
recall: 관련이 있을 때 저장된 정보를 가져옵니다.
forget: 더 이상 보존하지 않아야 하는 정보를 삭제합니다.

MCP 어댑터는 메모리를 자동으로 추출하지 않으므로, 에이전트 지침에는 에이전트가 언제 remember를 호출해야 하는지 명확히 밝혀야 합니다. 대화가 완료될 때마다 내용을 검사하고 저장한다고 가정하지 마세요.

고급 통합 팁

프로바이더 로직을 코어 외부에 두기

loci 코어는 Python 표준 라이브러리만 사용합니다. 모델 호출, API 키, 프로바이더 SDK는 애플리케이션이 관리합니다. 의미 추출에 모델이 필요하다면 코어에 프로바이더 의존성을 추가하는 대신 호스트에서 ModelExtractor를 주입하세요.

호스트에서 수명 주기 작업 실행하기

loci는 메모리 구조, 통합, 감쇠 동작을 정의하지만 일일 작업을 예약하지는 않습니다. 호스트의 cron, s6, systemd 또는 이에 준하는 스케줄러를 사용해 일일 작업을 실행하세요.

컨텍스트 제한 유지하기

전체 데이터베이스를 모든 프롬프트에 추가해 순위가 지정된 컨텍스트 블록을 우회하지 마세요. 12개 사실 제한은 중요하고 시의적절하며 최근의 정보를 우선시하면서 컨텍스트 증가를 제어하기 위해 존재합니다.

적절한 어댑터 사용하기

MCP 클라이언트 간 이식성이 중요하고 명시적인 메모리 작업을 허용할 수 있다면 MCP를 선택하세요.
모델 호출 후 자동 추출과 모든 호출 전 메모리 주입이 필요하다면 Hermes를 선택하세요.
애플리케이션이 에이전트 루프를 관리하고 지속성과 프롬프트 구성을 정밀하게 제어해야 한다면 직접 Python API를 선택하세요.

전송과 세션은 호스트가 관리하도록 하기

에이전트 루프, 도구 디스패치, 세션, 전송, 인증은 코어의 책임 범위 밖에 있습니다. Hermes, OpenClaw, Claude Code와 같은 호스트는 주변 런타임을 관리하고, 어댑터는 호스트별 전송과 인증을 처리합니다.

테스트 스위트 실행

pytest -q

이 프로젝트에는 임시 파일의 실제 SQLite 저장소를 대상으로 실행되는 92개의 테스트가 포함되어 있습니다. 저장소 자체를 모의 처리하지 않으므로 실제 배포에서 사용하는 것과 동일한 저장 기술을 기준으로 동작을 검증하는 데 도움이 됩니다.

결론

loci는 별도의 서버 없이 AI 에이전트에 간결하고 타입이 지정된 영구 메모리 계층을 제공합니다. 공유 코어는 메모리 구조와 수명 주기를 처리하고, MCP, Hermes 또는 자체 Python 에이전트가 주변 런타임을 제공합니다. 호스트에 맞는 어댑터로 시작하고, 추출과 예약의 책임을 명확히 유지하며, 순위가 지정된 컨텍스트 주입을 사용해 메모리가 프롬프트를 압도하지 않도록 하세요.