에이전트의 세션 간 기억 상실 문제를 해결하는 로컬 메모리 라이브러리 brainctl 공개

실용적 조언

pip install brainctl 명령어로 즉시 설치하여 기존 Python 에이전트 프로젝트에 통합할 수 있다.
LangChain이나 CrewAI를 사용 중이라면 제공된 어댑터를 활용해 기존 코드를 최소한으로 수정하며 적용 가능하다.

섹션별 상세

에이전트가 이전 세션의 맥락을 유지하지 못하는 문제를 해결하기 위해 SQLite 기반의 영구 저장소를 구현했다. Brain 객체를 생성하고 orient() 메서드를 호출하면 마지막 세션이 종료된 지점부터 데이터를 불러와 에이전트의 상태를 복구한다. 별도의 외부 서버나 API 키 없이 로컬 파일 하나로 모든 메모리 작업이 완결되도록 설계됐다.

python

from agentmemory import Brain
brain = Brain(agent_id="my-agent")
context = brain.orient() # picks up where last session left off

brainctl 라이브러리를 사용하여 이전 세션의 메모리를 불러오고 에이전트의 맥락을 설정하는 기본 코드

메모리 검색과 관리 효율성을 높이기 위해 FTS5 전체 텍스트 검색과 지식 그래프 구조를 도입했다. 중복되는 기억을 거부하는 'Write gate' 로직을 통해 저장 공간 낭비를 방지하고 데이터의 순도를 유지한다. 모든 메모리 연산 과정에서 LLM 호출을 배제하여 비용 발생을 차단하고 처리 속도를 극대화했다.

다양한 개발 환경과의 호환성을 위해 192개의 도구를 포함한 MCP 서버 기능을 제공한다. Claude Desktop 및 VS Code와 연동이 가능하며, 기존의 LangChain이나 CrewAI 프레임워크 사용자를 위한 전용 어댑터도 포함되어 있다. MIT 라이선스로 배포되어 상업적 이용이 자유롭고 PyPI를 통해 즉시 설치하여 사용할 수 있다.

용어 해설

전체 텍스트 검색 5(FTS5): — SQLite에서 제공하는 가상 테이블 모듈로, 대량의 텍스트 데이터 내에서 특정 단어나 구문을 매우 빠르게 검색할 수 있는 기능을 제공한다. 에이전트의 메모리 시스템에서 과거 대화나 지식을 효율적으로 찾아내기 위한 핵심 기술로 활용된다.
지식 그래프(Knowledge Graph): — 개체 간의 관계를 네트워크 구조로 표현하여 데이터의 맥락과 의미를 저장하는 방식이다. 단순한 텍스트 저장을 넘어 정보 사이의 연결 고리를 유지함으로써 에이전트가 복잡한 인과 관계나 맥락을 더 잘 이해하도록 돕는다.
모델 컨텍스트 프로토콜 서버(MCP Server): — Model Context Protocol의 약자로, AI 모델이 외부 도구나 데이터 소스에 표준화된 방식으로 접근할 수 있게 해주는 인터페이스이다. 이를 통해 Claude Desktop이나 VS Code 같은 환경에서 에이전트가 다양한 도구를 즉시 활용할 수 있다.

언급된 도구

brainctl추천링크

에이전트용 로컬 메모리 및 지식 그래프 관리 라이브러리

SQLite추천

로컬 데이터 저장 및 FTS5 검색 엔진

MCP추천

Claude 및 VS Code 연동을 위한 모델 컨텍스트 프로토콜

언급된 리소스

GitHubbrainctl GitHub Repository

문서brainctl PyPI Project Page