MCP로 영구 기억 서버 만들기: 최소 구현과 함정 체크리스트

AI 에이전트에게 영구적인 기억을 부여하고 싶다. 게다가 모델을 교체하더라도 기억은 남기고 싶다. 이를 실현하는 구체적인 방안이 기억을 MCP (Model Context Protocol) 서버로서 외부에 두는 것이다. 기억이 모델로부터 독립되기 때문에, MCP 대응 클라이언트라면 다른 모델에서도 동일한 기억을 참조할 수 있다.

이 기사는 직접 구현하는 측에 초점을 맞추어, 기억 MCP 서버의 최소 구현과 운용 시 빠지기 쉬운 함정의 체크리스트를 코드 중심으로 정리한다.

설계 사상(왜 동사로 도구를 나누는지, 왜 recall에서 전체를 반환하지 않는지)은 별도의 기사로 나누어 다룬다. 여기서는 구현에 집중한다.

공개할 도구는 3개로 압축한다.

recall_memory

… 관련 있는 기억만 추출한다 (전체 덤프를 하지 않음) -
save_memory

… 1개의 기억 = 1개의 사실로 기록한다 (기본값은 가설) -
list_memories

… scope(범위)를 지정하여 목록을 확인한다

기억은 확정도에 따라 3개 계층으로 나눈다: tentative (가설) / confirmed (확정) / working (실행). 판단에 사용해도 좋은 것은 확정(confirmed)과 실행(working)뿐이다. 신규 저장 시에는 가설(tentative)부터 시작한다.

1개의 기억 = 1개의 행. scope (용도 경계)와 tier (확정도)를 반드시 갖게 한다. SQLite라면 최소한 이 정도면 된다.

CREATE TABLE memory (
id TEXT PRIMARY KEY,
fact TEXT NOT NULL, -- 1건의 전제·결정·취향
...

deleted를 처음부터 넣어두는 것이 은근히 효과적이다. 오래된 전제를 물리적으로 삭제하지 않고 내릴 수 있으므로, 철회 및 복원이 가능하다.

TypeScript (@modelcontextprotocol/sdk)를 이용한 최소 골격이다. stdio 트랜스포트(transport)로 클라이언트에 연결한다.

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
...

이 부분이 설계의 핵심이다. recall은 필터링을 필수로 하여 전체 조회를 금지하고, save는 scope를 필수로 하여 경계를 넘지 않도록 한다.

server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
...

description은 모델에 대한 운용 지시로서 역할을 한다. 저장 기준(일반적인 사실은 저장하지 않음·1개의 사실만 저장)을 여기에 적어두면, 쓰기 폭주를 눈에 띄게 줄일 수 있다.

핵심은 recall이다. 반환하기 전에 반드시 필터링하고, 상한선(limit)을 설정한다.

server.setRequestHandler(CallToolRequestSchema, async (req) => {
const { name, arguments: args } = req.params;
if (name === "recall_memory") {
...

이로써 "관련 있는 확정 기억만을, 상한선을 두어, scope 경계를 지키며 추출하는" 최소한의 기억 MCP 서버가 동작한다.

구현을 한 차례 마쳤다면, 다음 사항을 확인하라. 단순하게 만들면 전부 빠지게 된다.

• recall이 전체를 반환하고 있지는 않은가… query / scope를 필수화하고, limit를 서버 측에서 제한한다.
• 가설(tentative)이 판단에 섞여 들어가지 않는가… recall의 기본값은 confirmed / working만 포함한다.
• scope를 선택 사항으로 두지 않았는가… 선택 사항이면 모델이 지정하지 않아 경계를 침범한다. 필수 사항으로 하되 기본 scope를 갖지 않도록 한다.
• save가 폭주하고 있지는 않은가… 중복 방지 로직 + description에 저장 기준을 명시한다.
• 반환값에 확정도와 신선도를 담았는가… tier와 updated_at을 반환하여, 모든 데이터가 동일한 비중을 갖지 않게 한다.
• 철회 및 강등이 가능한가… 논리 삭제(logical delete) 컬럼을 처음부터 준비한다. 확정(confirmed)으로의 승격은 빈도가 낮은 별도 처리로 분리한다.
• 1기억 1사실이 되어 있는가… 여러 사실을 묶어서 저장하면 나중에 일부만 업데이트할 수 없다.

기억 (Memory) MCP 서버 구현에서 효과적인 것은, 스토리지의 선택보다 도구 (Tool)의 입력 스키마 (Input Schema)로 제약하는 것입니다. recall에서 모든 항목을 반환하지 않도록 하고, save에서 scope를 필수 항목으로 지정하며, 반환값에 확신도 (Confidence)를 포함합니다. 이 세 가지만 적용해도 기억은 "섞이지 않고, 흐트러지지 않으며, 오래된 지도로 폭주하지 않는" 상태에 가까워집니다.

설계의 사고방식(왜 동사로 도구를 나누는지, recall을 검색에 가깝게 만드는 이유)은 "MCP로 AI에 영구 기억을 부여하기: 기억 레이어의 인터페이스 설계와 함정"에 작성되어 있습니다.

기억을 모델 외부에 두고, 어떤 AI에 삽입하더라도 동일한 문맥이 돌아오는 메커니즘을 실전 기록과 함께 키워나가고 있습니다: 에이전트 메모리즈 (Agent Memories)