Labsco
JinHo-von-Choi logo

Memento-cmp

โ˜… 123

from JinHo-von-Choi

A Three-Layer Memory Architecture for LLMs (Redis + Postgres + Vector) MCP

๐Ÿ”ฅ๐Ÿ”ฅ๐Ÿ”ฅโœ“ VerifiedAccount requiredNeeds API keys

๐Ÿ“– English Documentation

Memento MCP

AI์—๊ฒŒ ๊ธฐ์–ต์„ ์ค๋‹ˆ๋‹ค. ๊ทธ๋ฆฌ๊ณ  ๊ทธ ๊ธฐ์–ต์„ ๋ฐœํŒ์œผ๋กœ ์„ฑ์žฅํ•˜๊ฒŒ ํ•ฉ๋‹ˆ๋‹ค.

๋งค์ผ ์•„์นจ ๊ธฐ์–ต์ด ๋ฆฌ์…‹๋˜๋Š” ์‹ ์ž…์ง์›์„ ์ƒ์ƒํ•ด๋ณด๋ผ. ์–ด์ œ ๊ฐ€๋ฅด์นœ ๊ฒƒ๋„, ์ง€๋‚œ์ฃผ ํ•จ๊ป˜ ํ•ด๊ฒฐํ•œ ๋ฌธ์ œ๋„, ์ทจํ–ฅ๋„ ์ „๋ถ€ ๊นŒ๋จน๋Š”๋‹ค. Memento MCP๋Š” ์ด ์‹ ์ž…์—๊ฒŒ ๊ธฐ์–ต์„ ์‹ฌ์–ด์ค€๋‹ค.

Memento MCP๋Š” MCP(Model Context Protocol) ๊ธฐ๋ฐ˜ ์—์ด์ „ํŠธ ์žฅ๊ธฐ ๊ธฐ์–ต ์„œ๋ฒ„๋‹ค. ์„ธ์…˜์ด ์ข…๋ฃŒ๋˜์–ด๋„ ์ค‘์š”ํ•œ ์‚ฌ์‹ค, ๊ฒฐ์ •, ์—๋Ÿฌ ํŒจํ„ด, ์ ˆ์ฐจ๋ฅผ ์œ ์ง€ํ•˜๊ณ  ๋‹ค์Œ ์„ธ์…˜์—์„œ ๋ณต์›ํ•œ๋‹ค.

๋‹จ์ˆœํ•œ ๊ธฐ์–ต์˜ ๋„์„œ๊ด€์ด ์•„๋‹ˆ๋‹ค. ํ”ผ๋“œ๋ฐฑ์ด ์Œ“์ด๋ฉด ์—ฐ๊ฒฐ์ด ๊ฐ•ํ•ด์ง€๊ณ , ๊ฒฝํ—˜์ด ๋ฐ˜๋ณต๋˜๋ฉด ํŒจํ„ด์ด ์ถ”์ƒํ™”๋˜๊ณ , ์„ธ์…˜์ด ์ด์–ด์ง€๋ฉด ์ด์•ผ๊ธฐ๊ฐ€ ์ƒ๊ธด๋‹ค. ๊ธฐ์–ตํ•˜๋Š” AI๊ฐ€ ์•„๋‹ˆ๋ผ ๊ฒฝํ—˜์œผ๋กœ ์„ฑ์žฅํ•˜๋Š” AI๋ฅผ ์ง€ํ–ฅํ•œ๋‹ค.

[!TIP] ์„ค์น˜ยท์„ค์ •์„ ์ง์ ‘ ๋‹ค๋ฃจ๊ธฐ ๋ถ€๋‹ด์Šค๋Ÿฝ๋‹ค๋ฉด Claude CodeยทCursorยทCodex ๊ฐ™์€ AI ์–ด์‹œ์Šคํ„ดํŠธ์— ๋‹ค์Œ ํ•œ ๋ฌธ์žฅ์„ ์ „๋‹ฌํ•˜๋ฉด ๋œ๋‹ค.

"memento-mcp ์ €์žฅ์†Œ๋ฅผ ๋‚ด ํ™˜๊ฒฝ์— ์„ค์น˜ํ•˜๊ณ , docs/INSTALL.md์™€ SKILL.md๋ฅผ ์ฝ์–ด ๊ถŒ์žฅ ์„ค์ •์„ ์ ์šฉํ•œ ๋’ค ๋™์ž‘์„ ๊ฒ€์ฆํ•ด ์ค˜."

์˜์กด์„ฑ ์„ค์น˜, .env ๊ตฌ์„ฑ, MCP ๋“ฑ๋ก, ํ—ฌ์Šค ์ฒดํฌ๊นŒ์ง€ AI๊ฐ€ ์•ˆ๋‚ดํ•œ๋‹ค. ์ž์„ธํ•œ ์œ„์ž„ ์ ˆ์ฐจ๋Š” docs/INSTALL.md ์ฐธ๊ณ .

30์ดˆ ์ฒดํ—˜

AI์—๊ฒŒ ๋ฌด์–ธ๊ฐ€๋ฅผ ๊ธฐ์–ต์‹œํ‚ค๊ณ , ๋‹ค์Œ ์„ธ์…˜์—์„œ ๊บผ๋‚ด ๋ณด๋Š” ํ๋ฆ„์ด๋‹ค:

Copy & paste โ€” that's it
[์„ธ์…˜ 1]
์‚ฌ์šฉ์ž: "์šฐ๋ฆฌ ํ”„๋กœ์ ํŠธ๋Š” PostgreSQL 15๋ฅผ ์“ฐ๊ณ , ํ…Œ์ŠคํŠธ๋Š” Vitest๋กœ ๋Œ๋ ค"
 โ†’ AI๊ฐ€ remember ํ˜ธ์ถœ โ†’ ํŒŒํŽธ 2๊ฐœ ์ €์žฅ

[์„ธ์…˜ 2 โ€” ๋‹ค์Œ ๋‚ ]
 โ†’ AI๊ฐ€ context ํ˜ธ์ถœ โ†’ "PostgreSQL 15 ์‚ฌ์šฉ", "Vitest ํ…Œ์ŠคํŠธ" ์ž๋™ ๋ณต์›
์‚ฌ์šฉ์ž: "ํ…Œ์ŠคํŠธ ์–ด๋–ป๊ฒŒ ๋Œ๋ฆฌ๋”๋ผ?"
 โ†’ AI๊ฐ€ recall ํ˜ธ์ถœ โ†’ "Vitest๋กœ ํ…Œ์ŠคํŠธ ์‹คํ–‰" ํŒŒํŽธ ๋ฐ˜ํ™˜
 โ†’ AI: "์ด ํ”„๋กœ์ ํŠธ๋Š” Vitest๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค. npx vitest๋กœ ์‹คํ–‰ํ•˜์„ธ์š”."

๋งค ์„ธ์…˜๋งˆ๋‹ค ๊ฐ™์€ ์„ค๋ช…์„ ๋ฐ˜๋ณตํ•  ํ•„์š”๊ฐ€ ์—†๋‹ค.

์„ค์น˜

ํ•„์ˆ˜: Node.js 20+, PostgreSQL (pgvector ํ™•์žฅ)

Copy & paste โ€” that's it
cp .env.example.minimal .env
# .env ๊ฐ’์„ ํŽธ์ง‘ํ•œ ๋’ค ์…ธ์— ๋ฐ˜์˜
export $(grep -v '^#' .env | grep '=' | xargs)
npm install
npm run migrate
node server.js

OpenAI API ์—†์ด ๋กœ์ปฌ ์ž„๋ฒ ๋”ฉ์„ ์‚ฌ์šฉํ•˜๋ ค๋ฉด .env์— EMBEDDING_PROVIDER=transformers๋ฅผ ์ถ”๊ฐ€ํ•œ๋‹ค. ๊ธฐ๋™ ์‹œ Xenova/multilingual-e5-small ๋ชจ๋ธ์„ ์ž๋™์œผ๋กœ ๋‹ค์šด๋กœ๋“œํ•œ๋‹ค. ๋‹จ, OpenAI ์ž„๋ฒ ๋”ฉ์œผ๋กœ ์ด๋ฏธ ์ €์žฅ๋œ ๋ฐ์ดํ„ฐ์™€ ํ˜ผ์šฉํ•˜๋ฉด ์ฐจ์›์ด ๋ถˆ์ผ์น˜ํ•˜๋ฏ€๋กœ ์ƒˆ๋กœ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜๋œ DB์—์„œ๋งŒ ์‚ฌ์šฉํ•  ๊ฒƒ.

์„œ๋ฒ„๊ฐ€ ๋œฌ ๋’ค์—๋Š” First Memory Flow๋กœ ๋™์ž‘์„ ๊ฒ€์ฆํ•œ๋‹ค.

๋‹ค๋ฅธ ํ”Œ๋žซํผ ์„ค์ •์€ ์œ„ ํ˜ธํ™˜ ํ”Œ๋žซํผ ํ…Œ์ด๋ธ” ์ฐธ์กฐ.

์—…๋ฐ์ดํŠธ

Copy & paste โ€” that's it
cd ~/memento-mcp
git pull origin main
npm install
npm run migrate
# ์„œ๋น„์Šค ์žฌ์‹œ์ž‘ (systemd / pm2 / docker ๋“ฑ ํ™˜๊ฒฝ์— ๋งž๊ฒŒ)
  • npm run migrate๋Š” .env์˜ DB ์„ค์ •์„ ์ž๋™์œผ๋กœ ์‚ฌ์šฉํ•œ๋‹ค. DATABASE_URL ์ˆ˜๋™ ์ง€์ • ๋ถˆํ•„์š”.

  • pgvector ์Šคํ‚ค๋งˆ๋Š” ์ž๋™ ๊ฐ์ง€๋œ๋‹ค. PGVECTOR_SCHEMA ์„ค์ •์€ ๋Œ€๋ถ€๋ถ„ ๋ถˆํ•„์š”.

Claude Code ์—ฐ๋™

claude mcp add CLI๋กœ ๋“ฑ๋กํ•œ๋‹ค (HTTP ํƒ€์ž… MCP ์„œ๋ฒ„๋Š” settings.json์— ์ˆ˜๋™ ๊ธฐ์žฌํ•ด๋„ ์ธ์‹๋˜์ง€ ์•Š๋Š”๋‹ค).

Copy & paste โ€” that's it
claude mcp add memento http://localhost:57332/mcp \
 --transport http \
 --scope user \
 --header "Authorization: Bearer YOUR_ACCESS_KEY"

๋“ฑ๋ก์€ ~/.claude.json์— ์ €์žฅ๋œ๋‹ค. ํ™•์ธ:

Copy & paste โ€” that's it
claude mcp list
# memento: http://localhost:57332/mcp (HTTP) - โœ“ Connected

ํ”„๋กœ์ ํŠธ ๋‹จ์œ„๋กœ ๊ณต์œ ํ•˜๋ ค๋ฉด ์ €์žฅ์†Œ ๋ฃจํŠธ์˜ .mcp.json์— ๊ธฐ์žฌํ•œ๋‹ค. ์ƒ์„ธ ์„ค์ •์€ Claude Code Configuration ์ฐธ์กฐ.

Codex Desktop ์—ฐ๋™

Codex Desktop ๋“ฑ ์ผ๋ถ€ MCP ํด๋ผ์ด์–ธํŠธ๋Š” deferred/lazy tool discovery๋ฅผ ์“ด๋‹ค. tool_search๊ฐ€ ๊ฒ€์ƒ‰์–ด์™€ limit์— ๋”ฐ๋ผ ์ผ๋ถ€ ๋„๊ตฌ๋งŒ ๋…ธ์ถœํ•˜๋ฏ€๋กœ, ํ•ญ์ƒ ์กด์žฌํ•˜๋Š” recall์ด ์ €์žฅ ํŽธํ–ฅ ์ฟผ๋ฆฌ+๋‚ฎ์€ limit์—์„œ ๋น ์งˆ ์ˆ˜ ์žˆ๋‹ค. recall์ด ์•ˆ ๋ณด์ด๋ฉด ๋” ๋„“์€ ์ฟผ๋ฆฌ์™€ limit 20 ์ด์ƒ์œผ๋กœ ์žฌ๊ฒ€์ƒ‰ํ•œ๋‹ค. ๊ถŒ์žฅ: ์—์ด์ „ํŠธ system prompt/instructions์— ์ด ์žฌ๊ฒ€์ƒ‰ ๊ทœ์น™์„ ๋ฏธ๋ฆฌ ์‹ฌ์–ด ์ดˆ๊ธฐ discovery ๋ฃจํ”„๋ฅผ ์ฐจ๋‹จํ•œ๋‹ค.

  • query: memento context recall remember reflect batch_remember search_traces reconstruct_history

  • limit: 20 ์ด์ƒ

์ง€์› ํ™˜๊ฒฝ

ํ™˜๊ฒฝ ๊ถŒ์žฅ๋„ ์‹œ์ž‘ ๋ฌธ์„œ Linux / macOS ๊ถŒ์žฅ Quick Start Windows + WSL2 ๊ฐ€์žฅ ๊ถŒ์žฅ Windows WSL2 Setup Windows + PowerShell ์ œํ•œ ์ง€์› Windows PowerShell Setup

ํ˜ธํ™˜ ํ”Œ๋žซํผ

Memento๋Š” MCP(Model Context Protocol) ํ‘œ์ค€ ์„œ๋ฒ„๋‹ค. Claude Code๋ฟ ์•„๋‹ˆ๋ผ, MCP๋ฅผ ์ง€์›ํ•˜๋Š” ๋ชจ๋“  AI ํ”Œ๋žซํผ์—์„œ ์‚ฌ์šฉํ•  ์ˆ˜ ์žˆ๋‹ค.

ํ”Œ๋žซํผ ์„ค์ • ์œ„์น˜ ์—ฐ๊ฒฐ ๋ฐฉ์‹ Claude Code claude mcp add CLI (~/.claude.json) ๋˜๋Š” .mcp.json Streamable HTTP Claude Desktop claude_desktop_config.json Streamable HTTP Claude.ai Web Settings > Integrations OAuth (RFC 7591) Cursor .cursor/mcp.json Streamable HTTP Windsurf ~/.codeium/windsurf/mcp_config.json Streamable HTTP GitHub Copilot VS Code MCP Marketplace Streamable HTTP Codex CLI ~/.codex/config.toml Streamable HTTP ChatGPT Desktop Developer Mode > Apps OAuth (RFC 7591) Continue config.json Streamable HTTP

๊ณตํ†ต ์„ค์ •: ์„œ๋ฒ„ URL http://localhost:57332/mcp, Authorization ํ—ค๋”์— Bearer YOUR_ACCESS_KEY.

Claude.ai Web / ChatGPT ์—ฐ๋™์€ OAuth๋ฅผ ์‚ฌ์šฉํ•œ๋‹ค. ๋ฐœ๊ธ‰ํ•œ API ํ‚ค(mmcp_xxx)๋ฅผ client_id๋กœ ์ž…๋ ฅํ•˜๋ฉด Dynamic Client Registration(RFC 7591) ์—†์ด ๋ฐ”๋กœ ์—ฐ๊ฒฐ๋œ๋‹ค. ์‹ ๋ขฐ ๋„๋ฉ”์ธ(claude.ai, chatgpt.com)์˜ redirect URI๋Š” ์ž๋™ ์Šน์ธ๋œ๋‹ค.

ํ”Œ๋žซํผ๋ณ„ ์ƒ์„ธ ์„ค์ •์€ ์—ฐ๋™ ๊ฐ€์ด๋“œ ์ฐธ์กฐ.

7๊ฐ€์ง€ ํŒŒํŽธ ์œ ํ˜•

์œ ํ˜• ์„ค๋ช… ์šฉ๋„ fact ์‚ฌ์‹ค ์„ค์ •๊ฐ’, ๊ฒฝ๋กœ, ๋ฒ„์ „ ๋“ฑ ๊ฐ๊ด€์  ์ •๋ณด decision ์˜์‚ฌ๊ฒฐ์ • ์•„ํ‚คํ…์ฒ˜ ์„ ํƒ, ๊ธฐ์ˆ  ์Šคํƒ ๊ฒฐ์ •๊ณผ ๊ทผ๊ฑฐ error ์—๋Ÿฌ ๋ฐœ์ƒํ•œ ์—๋Ÿฌ์™€ ์›์ธ, ํ•ด๊ฒฐ ๋ฐฉ๋ฒ• preference ์„ ํ˜ธ ์‚ฌ์šฉ์ž ์Šคํƒ€์ผ, ์ฝ”๋”ฉ ๊ทœ์น™, ์ž‘์—… ๋ฐฉ์‹ procedure ์ ˆ์ฐจ ๋ฐฐํฌ, ๋นŒ๋“œ, ํ…Œ์ŠคํŠธ ๋“ฑ ๋ฐ˜๋ณต ๊ฐ€๋Šฅํ•œ ๋‹จ๊ณ„ relation ๊ด€๊ณ„ ์—”ํ‹ฐํ‹ฐ ๊ฐ„ ์—ฐ๊ฒฐ, ์˜์กด์„ฑ, ์†Œ์œ  ๊ด€๊ณ„ episode ์—ํ”ผ์†Œ๋“œ ์ „ํ›„๊ด€๊ณ„๋ฅผ ํฌํ•จํ•˜๋Š” ์„œ์‚ฌ ๊ธฐ์–ต (1000์ž, ๋‚˜๋จธ์ง€๋Š” 300์ž)

ํ•ต์‹ฌ ๊ธฐ๋Šฅ

๊ธฐ๋Šฅ ์„ค๋ช… remember ์ค‘์š”ํ•œ ์ •๋ณด๋ฅผ ์›์ž์  ํŒŒํŽธ์œผ๋กœ ๋ถ„ํ•ดํ•˜์—ฌ ์ €์žฅ. MEMENTO_REMEMBER_ATOMIC=true ์‹œ quota check + INSERT๋ฅผ ๋‹จ์ผ ํŠธ๋žœ์žญ์…˜์œผ๋กœ ์›์žํ™”. recall ํ‚ค์›Œ๋“œ + ์‹œ๋งจํ‹ฑ 3๊ณ„์ธต ๊ฒ€์ƒ‰์œผ๋กœ ํ•„์š”ํ•œ ๊ธฐ์–ต๋งŒ ๋ฐ˜ํ™˜. SearchScope๊ฐ€ workspace/caseId/affect ๋“ฑ scope๋ฅผ L1~L3 ์ „ ๋ ˆ์ด์–ด์— ์ •ํ•ฉ ์ ์šฉ. context ์„ธ์…˜ ์‹œ์ž‘ ์‹œ ํ•ต์‹ฌ ๋งฅ๋ฝ์„ ์ž๋™ ๋ณต์› ์ž๋™ ์ •๋ฆฌ ์ค‘๋ณต ๋ณ‘ํ•ฉ, ๋ชจ์ˆœ ํƒ์ง€, ์ค‘์š”๋„ ๊ฐ์‡ , TTL ๊ธฐ๋ฐ˜ ๋ง๊ฐ storage ์–ด๋Œ‘ํ„ฐ ๊ณ„์ธต lib/storage/ ์‹ ์„ค. getStorage() ํŒฉํ† ๋ฆฌ๊ฐ€ MEMENTO_STORAGE ENV์— ๋”ฐ๋ผ PgVectorStore(๊ธฐ๋ณธ) ๋˜๋Š” SqliteVecStore(v4.1 ์˜ˆ์ •)๋ฅผ ๋ฐ˜ํ™˜. ๋งํฌ ์žฌํ†ตํ•ฉ tool_feedback ํ”ผ๋“œ๋ฐฑ์ด fragment_links์˜ weight/confidence์— ์‹ค์‹œ๊ฐ„ ๋ฐ˜์˜ (ReconsolidationEngine). ๋ชจ์ˆœ ๋งํฌ๋Š” ์ž๋™ ๊ฒฉ๋ฆฌ(quarantine). ํ™•์‚ฐ ํ™œ์„ฑํ™” recall ์‹œ contextText๋ฅผ ์ „๋‹ฌํ•˜๋ฉด ๊ด€๋ จ ํŒŒํŽธ์˜ activation_score๋ฅผ ์„ ์ œ์ ์œผ๋กœ ๋ถ€์ŠคํŠธํ•˜์—ฌ ๋งฅ๋ฝ ์—ฐ๊ด€์„ฑ ๋†’์€ ๊ฒฐ๊ณผ ์šฐ์„  ๋ฐ˜ํ™˜ (SpreadingActivation). ์—ํ”ผ์†Œ๋“œ ์—ฐ์†์„ฑ reflect ํ›„ ์ƒ์„ฑ๋œ episode ํŒŒํŽธ ๊ฐ„ preceded_by ์—ฃ์ง€๋ฅผ ์ž๋™ ์ƒ์„ฑํ•˜์—ฌ ๊ฒฝํ—˜ ํ๋ฆ„์„ ๊ทธ๋ž˜ํ”„๋กœ ๋ณด์กด (EpisodeContinuityService). ๊ด€๋ฆฌ ์ฝ˜์†” ๊ธฐ์–ต ํƒ์ƒ‰, ์ง€์‹ ๊ทธ๋ž˜ํ”„, ํ†ต๊ณ„ ๋Œ€์‹œ๋ณด๋“œ, API ํ‚ค ๊ทธ๋ฃน/์ƒํƒœ ํ•„ํ„ฐ, daily-limit ์ธ๋ผ์ธ ํŽธ์ง‘ OAuth ์—ฐ๋™ RFC 7591 Dynamic Client Registration, Claude.ai / ChatGPT Web ํ†ตํ•ฉ ์ง€์› Workspace ๊ฒฉ๋ฆฌ ๊ฐ™์€ ํ‚ค ๋‚ด์—์„œ๋„ ํ”„๋กœ์ ํŠธยท์ง์ข…ยทํด๋ผ์ด์–ธํŠธ ๋‹จ์œ„๋กœ ๊ธฐ์–ต์„ ๋ถ„๋ฆฌ. api_keys.default_workspace๋กœ ์ž๋™ ํƒœ๊น…, ๊ฒ€์ƒ‰ ์‹œ ์ž๋™ ํ•„ํ„ฐ. ๋ฐฐ์น˜ ์ฒ˜๋ฆฌ batch_remember๋Š” multi-row ๋‹จ์ผ INSERT(256KB ๋˜๋Š” 500ํ–‰ chunk) + ๋น„๋™๊ธฐ ํ ์›Œ์ปค(BatchRememberWorker)๋กœ ์ž„๋ฒ ๋”ฉยทํ›„์ฒ˜๋ฆฌ๋ฅผ ๋…ผ๋ธ”๋กœํ‚น ์‹คํ–‰. async: true ์‹œ ackยท์žฌ์‹œ๋„(์ตœ๋Œ€ 3ํšŒ)ยทdead-letterยท๊ธฐ๋™ ๋ณต๊ตฌ(RPOPLPUSH reliable queue)๋กœ at-least-once ์ฒ˜๋ฆฌ ๋ณด์žฅ. batch_status(jobId) ๋„๊ตฌ๋กœ ์ฒ˜๋ฆฌ ์ƒํƒœ(queued/processing/completed/dead) ์กฐํšŒ ๊ฐ€๋Šฅ. ํ•ญ์ƒ ํ‘œ์ค€ ๋‹จ์ผ JSON-RPC ์‘๋‹ต ๋ฐ˜ํ™˜(stream deprecated). reflect๋Š” 5์นดํ…Œ๊ณ ๋ฆฌ๋ฅผ ๋‹จ์ผ ๋ฐฐ์น˜ ํ˜ธ์ถœ๋กœ ์œ„์ž„. EmbeddingWorker๋Š” ํ ๋ฌถ์Œ์„ generateBatchEmbeddings + multi-row UPDATE๋กœ ์ฒ˜๋ฆฌ. Consistency Gate fragments.morpheme_indexed ์ปฌ๋Ÿผ์œผ๋กœ ํ˜•ํƒœ์†Œ ์ธ๋ฑ์Šค ์™„๋ฃŒ ์—ฌ๋ถ€ ์ถ”์ . ๋ฏธ์™„๋ฃŒ ํŒŒํŽธ์€ L3 ํ˜•ํƒœ์†Œ ๊ฒ€์ƒ‰ ๊ฒฝ๋กœ์—์„œ ์ž๋™ ์ œ์™ธ. Mode preset recall-only / write-only / onboarding / audit JSON preset. X-Memento-Mode ํ—ค๋” ๋˜๋Š” api_keys.default_mode๋กœ ๋„๊ตฌ ๋…ธ์ถœ ๋ฒ”์œ„ ์ œํ•œ. Affective tagging fragments.affect ์ปฌ๋Ÿผ(neutral / frustration / confidence / surprise / doubt / satisfaction). remember / recall ์‹œ ๊ฐ์ • ๋ ˆ์ด๋ธ”๋กœ ํ•„ํ„ฐ๋ง. ๋กœ์ปฌ ์ž„๋ฒ ๋”ฉ EMBEDDING_PROVIDER=transformers๋กœ ์™ธ๋ถ€ API ์—†์ด @huggingface/transformers ํŒŒ์ดํ”„๋ผ์ธ ๊ธฐ๋ฐ˜ ์ž„๋ฒ ๋”ฉ(Xenova/multilingual-e5-small, 384d ๊ธฐ๋ณธ). ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ lint npm run lint:migrations๋กœ ์‹ ๊ทœ ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ ํŒŒ์ผ์˜ ๋ฒˆํ˜ธ ์ถฉ๋Œยท๊ทœ์•ฝ ์œ„๋ฐ˜์„ ์ปค๋ฐ‹ ์ „ ์ž๋™ ๊ฒ€์‚ฌ.

์ „์ฒด MCP ๋„๊ตฌ ๋ชฉ๋ก์€ SKILL.md ์ฐธ์กฐ.

CLI

์›๊ฒฉ MCP ์„œ๋ฒ„๋ฅผ ๋กœ์ปฌ ๋…ธ๋“œ ์—†์ด ์ง์ ‘ ์กฐ์ž‘ํ•  ์ˆ˜ ์žˆ๋‹ค. --remote URL --key KEY ์ „์—ญ ํ”Œ๋ž˜๊ทธ ๋˜๋Š” MEMENTO_CLI_REMOTE / MEMENTO_CLI_KEY ํ™˜๊ฒฝ๋ณ€์ˆ˜๋กœ ์ง€์ •ํ•œ๋‹ค.

Copy & paste โ€” that's it
# ์›๊ฒฉ ์„œ๋ฒ„์—์„œ recall (ํ™˜๊ฒฝ๋ณ€์ˆ˜ ๋ฐฉ์‹)
MEMENTO_CLI_REMOTE=https://example.com/mcp MEMENTO_CLI_KEY=mmcp_xxx memento-mcp recall "query"

# ์›๊ฒฉ ์„œ๋ฒ„์—์„œ recall (ํ”Œ๋ž˜๊ทธ ๋ฐฉ์‹)
memento-mcp recall "query" --remote https://example.com/mcp --key mmcp_xxx

# ํ‘œ ํ˜•์‹ ์ถœ๋ ฅ, ๊ฒฐ๊ณผ 5๊ฑด
memento-mcp recall "query" --format table --limit 5

# idempotency key๋กœ ์ค‘๋ณต ์ €์žฅ ๋ฐฉ์ง€
memento-mcp remember "๋‚ด์šฉ" --topic ํ”„๋กœ์ ํŠธ๋ช… --idempotency-key k1

--format table|json|csv ์ถœ๋ ฅ ํ˜•์‹ ์„ ํƒ, 14๊ฐœ ์„œ๋ธŒ๋ช…๋ น์— --help/-h ์ง€์›. ์ž์„ธํ•œ ํ”Œ๋ž˜๊ทธ๋Š” docs/cli.md.

API ์‘๋‹ต ๋ฉ”ํƒ€

recall / context ์‘๋‹ต์€ _meta: { searchEventId, hints, suggestion, serverTime } ํ•„๋“œ๋ฅผ ํฌํ•จํ•œ๋‹ค. serverTime์€ LLM ํด๋ผ์ด์–ธํŠธ์˜ ํ•™์Šต ์‹œ์  ์‹œ๊ฐ„ ๊ณ ์ฐฉ์„ ๋ฐฉ์ง€ํ•˜๊ธฐ ์œ„ํ•ด ๋งค ์‘๋‹ต๋งˆ๋‹ค ์„œ๋ฒ„ ํ˜„์žฌ ์‹œ๊ฐ์„ ๋…ธ์ถœํ•œ๋‹ค.

Copy & paste โ€” that's it
{
 "fragments": [...],
 "_meta": {
 "searchEventId": "evt-abc123",
 "hints": { "signal": "consider_context" },
 "suggestion": { "code": "large_limit_no_budget", "message": "..." },
 "serverTime": {
 "iso" : "2026-05-15T06:32:11.000Z",
 "epoch_ms" : 1747291931000,
 "display_kst": "2026๋…„ 5์›” 15์ผ (๋ชฉ) 15:32",
 "timezone" : "Asia/Seoul"
 }
 }
}

remember / link / forget / amend๋Š” dryRun: true ํŒŒ๋ผ๋ฏธํ„ฐ๋กœ ๋ถ€์ž‘์šฉ ์—†์ด ์˜ˆ์ƒ ๊ฒฐ๊ณผ๋งŒ ๋ฐ˜ํ™˜ํ•œ๋‹ค. ๋ชจ๋“  ์‘๋‹ต์— X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Resource ํ—ค๋”๊ฐ€ ํฌํ•จ๋˜๋ฉฐ master key ๋˜๋Š” limit=null ์„ค์ • ์‹œ ํ—ค๋”๋ฅผ ์ƒ๋žตํ•œ๋‹ค. recall์€ fields ๋ฐฐ์—ด๋กœ ๋ฐ˜ํ™˜ ํ•„๋“œ๋ฅผ 17๊ฐœ ํ™”์ดํŠธ๋ฆฌ์ŠคํŠธ ๋ฒ”์œ„๋กœ ์ œํ•œํ•  ์ˆ˜ ์žˆ๋‹ค. remember / batchRemember๋Š” idempotencyKey ํŒŒ๋ผ๋ฏธํ„ฐ๋กœ ๊ฐ™์€ key_id ๋ฒ”์œ„ ๋‚ด ์ค‘๋ณต ์ €์žฅ์„ ๋ฐฉ์ง€ํ•œ๋‹ค(์ตœ๋Œ€ 128์ž).

๋ณด์•ˆ

  • RBAC default-deny: TOOL_PERMISSIONS ๋งต์— ์—†๋Š” ๋„๊ตฌ๋ช…์€ ๊ถŒํ•œ๊ณผ ๋ฌด๊ด€ํ•˜๊ฒŒ ์ฆ‰์‹œ ๊ฑฐ๋ถ€.

  • ํ…Œ๋„ŒํŠธ ๊ฒฉ๋ฆฌ: forget / amend / link / fragment_history๋Š” SQL ๋ ˆ๋ฒจ key_id ์กฐ๊ฑด์œผ๋กœ ํƒ€ ํ…Œ๋„ŒํŠธ ํŒŒํŽธ ์ ‘๊ทผ ๋ถˆ๊ฐ€. "์—†์Œ"๊ณผ "๊ถŒํ•œ ์—†์Œ"์„ ๋™์ผ ๋ฉ”์‹œ์ง€๋กœ ์ฒ˜๋ฆฌํ•˜์—ฌ ์กด์žฌ ์—ฌ๋ถ€ ๋…ธ์ถœ ๋ฐฉ์ง€.

  • injectSessionContext: ํด๋ผ์ด์–ธํŠธ๊ฐ€ ์ „์†กํ•œ _keyId / _permissions ๋“ฑ ๋‚ด๋ถ€ ํ•„๋“œ๋ฅผ ์„œ๋ฒ„ ์ธ์ฆ ๊ฒฐ๊ณผ๋กœ ์žฌ์ฃผ์ž…ํ•˜์—ฌ ์„ธ์…˜ ์ปจํ…์ŠคํŠธ ์œ„์กฐ ์ฐจ๋‹จ.

  • Admin rate limit: /auth, /keys POST, /import POST์— IP ๊ธฐ๋ฐ˜ rate limit.

  • OpenAPI: GET /openapi.json ์—”๋“œํฌ์ธํŠธ(ENABLE_OPENAPI=true). master key๋Š” ์ „์ฒด ๊ฒฝ๋กœ, API key๋Š” permissions ํ•„ํ„ฐ ์ŠคํŽ™ ๋ฐ˜ํ™˜.

Symbolic Verification Layer

์„ ํƒ์  ์„ค๋ช… ๊ฐ€๋Šฅ์„ฑ, advisory ๋งํฌ ๋ฌด๊ฒฐ์„ฑ, ๊ทน์„ฑ ์ถฉ๋Œ ํƒ์ง€, ์ •์ฑ… ๊ทœ์น™ soft gating. 9 core ๋ชจ๋“ˆ + 5 ๊ทœ์น™ ํŒŒ์ผ. ๋ชจ๋“  ํ”Œ๋ž˜๊ทธ ๊ธฐ๋ณธ ๋น„ํ™œ์„ฑ.

Smart Recall

  • ProactiveRecall: remember() ์‹œ ํ‚ค์›Œ๋“œ ์˜ค๋ฒ„๋žฉ ๊ธฐ๋ฐ˜ ์œ ์‚ฌ ํŒŒํŽธ ์ž๋™ ๋งํฌ.

  • CaseRewardBackprop: case verification ์ด๋ฒคํŠธ ์‹œ ์ฆ๊ฑฐ ํŒŒํŽธ importance ์ž๋™ ์—ญ์ „ํŒŒ.

  • SearchParamAdaptor: ์‚ฌ์šฉ ํŒจํ„ด ๊ธฐ๋ฐ˜ ๊ฒ€์ƒ‰ ์ž„๊ณ„๊ฐ’ ์ž๋™ ์ตœ์ ํ™”.

  • CBR(Case-Based Reasoning): recall(caseMode=true) ๋กœ ์œ ์‚ฌ ์‚ฌ๋ก€์˜ goal โ†’ events โ†’ outcome ํ๋ฆ„์„ ๊ฒ€์ƒ‰ํ•˜์—ฌ ๊ณผ๊ฑฐ ํ•ด๊ฒฐ ํŒจํ„ด ์žฌํ™œ์šฉ.

  • depth ํ•„ํ„ฐ: Planner/Executor ์—ญํ• ๋ณ„ ๊ฒ€์ƒ‰ ๊นŠ์ด ์ œ์–ด("high-level" / "detail" / "tool-level").

  • recall ์‘๋‹ต key_id: ๋ฐ˜ํ™˜ ํŒŒํŽธ์— ์†Œ์œ  ํ…Œ๋„ŒํŠธ ์‹๋ณ„์ž ํฌํ•จ.

  • Reconsolidation: tool_feedback ๊ธฐ๋ฐ˜ fragment_links weight/confidence ์‹ค์‹œ๊ฐ„ ๊ฐฑ์‹ (ENABLE_RECONSOLIDATION=true).

  • Spreading Activation: recall(contextText=...) ์ „๋‹ฌ ์‹œ ๋Œ€ํ™” ๋งฅ๋ฝ ๊ธฐ๋ฐ˜ ๊ด€๋ จ ํŒŒํŽธ ema_activation ์„ ์ œ ํ™œ์„ฑํ™”(ENABLE_SPREADING_ACTIVATION=true).

fragments.id๋Š” frag-{16์ž hex} text ํ˜•์‹์ด๋‹ค. UUID๊ฐ€ ์•„๋‹ˆ๋ฏ€๋กœ ์™ธ๋ถ€์—์„œ ID๋ฅผ ์ƒ์„ฑํ•˜๊ฑฐ๋‚˜ ํŒŒ์‹ฑํ•  ๋•Œ ์ฃผ์˜ํ•œ๋‹ค.

/metrics ์—”๋“œํฌ์ธํŠธ๊ฐ€ Prometheus ํ˜ธํ™˜ ํ˜•์‹์œผ๋กœ ๋ฉ”ํŠธ๋ฆญ์„ ๋…ธ์ถœํ•œ๋‹ค. ์ˆ˜์ง‘ยท์‹œ๊ฐํ™”๋Š” ์‚ฌ์šฉ์ž๊ฐ€ ์ž์œ ๋กญ๊ฒŒ ๊ตฌ์„ฑํ•œ๋‹ค.

๊ธฐ์–ต vs ๊ทœ์น™

Memento๊ฐ€ ์ฃผ์ž…ํ•˜๋Š” ๊ธฐ์–ต ํŒŒํŽธ์€ ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ๋ณด๋‹ค ์šฐ์„ ์ˆœ์œ„๊ฐ€ ๋‚ฎ๋‹ค. "PostgreSQL 15๋ฅผ ์“ด๋‹ค"๊ฐ™์€ ์‚ฌ์‹ค ๊ธฐ์–ต์€ ์ž˜ ์ž‘๋™ํ•˜์ง€๋งŒ, "ํ…Œ์ŠคํŠธ ์ž‘์„ฑ ์‹œ ๋ฐ˜๋“œ์‹œ Given-When-Then ํŒจํ„ด์„ ์“ธ ๊ฒƒ"๊ฐ™์€ ํ–‰๋™ ๊ทœ์น™์€ ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ์™€ ์ถฉ๋Œํ•˜๋ฉด ๋ฌด์‹œ๋  ์ˆ˜ ์žˆ๋‹ค.

ํ–‰๋™ ๊ทœ์น™์€ CLAUDE.md, AGENTS.md, ํ›…(hooks), ์Šคํ‚ฌ(skills) ๋“ฑ ์šฐ์„ ์ˆœ์œ„๊ฐ€ ๋†’์€ ์ฑ„๋„์— ์„ค์ •ํ•˜๋Š” ๊ฒƒ์„ ๊ถŒ์žฅํ•œ๋‹ค.

๋ฒค์น˜๋งˆํฌ

LongMemEval-S 500๋ฌธํ•ญ ๊ธฐ์ค€ ์„ฑ๋Šฅ:

์ง€ํ‘œ ์ ์ˆ˜ ๋น„๊ต ๊ฒ€์ƒ‰ recall@5 88.3% LongMemEval ๋…ผ๋ฌธ Stella 1.5B ๋Œ€๋น„ +8~18pp QA ์ •๋‹ต๋ฅ  45.4% temporal metadata ์ ์šฉ (baseline 40.4%) ํŒŒํŽธ ์ฒ˜๋ฆฌ๋Ÿ‰ 89,006๊ฐœ / 27์ดˆ ์ธ์ œ์Šค์ฒœ + ์ž„๋ฒ ๋”ฉ + ๊ฒ€์ƒ‰ ์ „์ฒด ํŒŒ์ดํ”„๋ผ์ธ

๊ฒ€์ƒ‰์€ 6๊ฐœ ๋ฌธํ•ญ ์œ ํ˜• ์ค‘ 5๊ฐœ์—์„œ 80% ์ด์ƒ recall์„ ๋‹ฌ์„ฑํ•œ๋‹ค. ๋‹ค๋งŒ ๊ฒ€์ƒ‰ recall(88.3%)๊ณผ QA ์ •๋‹ต๋ฅ (45.4%) ์‚ฌ์ด์— ํฐ gap์ด ์กด์žฌํ•œ๋‹ค. ์ด๋Š” ๊ฒ€์ƒ‰๋œ ํŒŒํŽธ์—์„œ ์ •๋‹ต์„ ํ•ฉ์„ฑํ•˜๋Š” reader ๋‹จ๊ณ„์˜ ํ•œ๊ณ„๋กœ, multi-session ์ถ”๋ก ๊ณผ ์‹œ๊ฐ„์ถ• ์ถ”๋ก ์—์„œ ํŠนํžˆ ๋‘๋“œ๋Ÿฌ์ง„๋‹ค.

์ƒ์„ธ ๋ถ„์„์€ Benchmark Report ์ฐธ์กฐ.

์‚ฌ์šฉ ํŒจํ„ด

Memento๋Š” ์‚ฌ์‹ค ๊ธฐ์–ต(fact cache)์— ์ตœ์ ํ™”๋˜์–ด ์žˆ๋‹ค. ์ „ํ›„๊ด€๊ณ„๊ฐ€ ์ค‘์š”ํ•œ ๊ฒฝ์šฐ:

  • episode ์œ ํ˜•์œผ๋กœ ์„œ์‚ฌ๋ฅผ ์ €์žฅํ•˜๋ฉด "์™œ ๊ทธ๋Ÿฐ ๊ฒฐ์ •์„ ํ–ˆ๋Š”์ง€"๊นŒ์ง€ ๋ณต์› ๊ฐ€๋Šฅ

  • contextSummary๋ฅผ ํ•จ๊ป˜ ์ €์žฅํ•˜๋ฉด recall ์‹œ ๋งฅ๋ฝ์ด ํ•จ๊ป˜ ๋ฐ˜ํ™˜๋จ

  • ๋ฉ”์ธ ๋ฉ”๋ชจ๋ฆฌ ์‹œ์Šคํ…œ(MEMORY.md ๋“ฑ)๊ณผ ๋ณ‘ํ–‰ํ•˜์—ฌ ์‚ฌ์‹ค ๊ฒ€์ƒ‰์€ Memento, ๋งฅ๋ฝ ๋ณต์›์€ ๋ฉ”์ธ ๋ฉ”๋ชจ๋ฆฌ๋กœ ์—ญํ•  ๋ถ„๋‹ดํ•˜๋Š” ์ด์›ํ™” ๊ตฌ์กฐ๋„ ํšจ๊ณผ์ 

๋ˆ„๊ฐ€ ์“ฐ๋ฉด ์ข‹์€๊ฐ€

  • Claude Code / Cursor / Windsurf ๋“ฑ AI ์—์ด์ „ํŠธ๋ฅผ ๋งค์ผ ์“ฐ๋Š” ๊ฐœ๋ฐœ์ž

  • ์„ธ์…˜๋งˆ๋‹ค ๊ฐ™์€ ์„ค๋ช…์„ ๋ฐ˜๋ณตํ•˜๋Š” ๊ฒŒ ์งœ์ฆ๋‚˜๋Š” ์‚ฌ๋žŒ

  • AI์—๊ฒŒ ๋‚ด ํ”„๋กœ์ ํŠธ ๋งฅ๋ฝ์„ ๊ธฐ์–ต์‹œํ‚ค๊ณ  ์‹ถ์€ ์‚ฌ๋žŒ

๋””๋ ‰ํ† ๋ฆฌ ๊ตฌ์กฐ

Copy & paste โ€” that's it
lib/
 memory/
 read/ # FragmentSearch, SearchScope, SearchSideEffects, CaseRecall ๋“ฑ
 write/ # MemoryRememberer, BatchRememberProcessor ๋“ฑ
 link/ # MemoryLinker, ReconsolidationEngine ๋“ฑ
 consolidate/ # MemoryConsolidator
 embedding/ # EmbeddingWorker, EmbeddingCache, MorphemeIndex
 signals/ # SpreadingActivation, CaseRewardBackprop ๋“ฑ
 processors/ # facade โ€” MemoryRecaller, MemoryReflector ๋“ฑ
 storage/ # PgVectorStore(๊ธฐ๋ณธ), SqliteVecStore(v4.1 ์˜ˆ์ •) ์–ด๋Œ‘ํ„ฐ ๊ณ„์ธต
 llm/ # dispatchChain, provider ๊ตฌํ˜„์ฒด
 symbolic/ # SymbolicVerificationLayer (opt-in)
docs/
 getting-started/ # ํ”Œ๋žซํผ๋ณ„ ์„ค์น˜ ๊ฐ€์ด๋“œ
 operations/ # ์šด์˜ ๊ฐ€์ด๋“œ (llm-providers, symbolic-hard-gate ๋“ฑ)
 features.md # ๋ชจ๋“ˆ ledger
 configuration.md # ํ™˜๊ฒฝ๋ณ€์ˆ˜ ์ „์ฒด ๋ ˆํผ๋Ÿฐ์Šค

๋” ์•Œ์•„๋ณด๊ธฐ

๋ฌธ์„œ ๋‚ด์šฉ Quick Start ์ƒ์„ธ ์„ค์น˜ ๊ฐ€์ด๋“œ Architecture ์‹œ์Šคํ…œ ๊ตฌ์กฐ, DB ์Šคํ‚ค๋งˆ, 3๊ณ„์ธต ๊ฒ€์ƒ‰, TTL Configuration ํ™˜๊ฒฝ ๋ณ€์ˆ˜, MEMORY_CONFIG, ์ž„๋ฒ ๋”ฉ Provider API Reference HTTP ์—”๋“œํฌ์ธํŠธ, ํ”„๋กฌํ”„ํŠธ, ๋ฆฌ์†Œ์Šค CLI ํ„ฐ๋ฏธ๋„ ๋ช…๋ น์–ด Internals ํ‰๊ฐ€๊ธฐ, ํ†ตํ•ฉ๊ธฐ, ๋ชจ์ˆœ ํƒ์ง€ Benchmark LongMemEval-S ๋ฒค์น˜๋งˆํฌ ์ƒ์„ธ ๋ถ„์„ Features ๋ชจ๋“ˆ ledger, ์‹คํ—˜ ํ”Œ๋ž˜๊ทธ, ENV ๋งคํ•‘ SKILL.md MCP ๋„๊ตฌ ์ „์ฒด ๋ ˆํผ๋Ÿฐ์Šค INSTALL.md ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜, ํ›… ์„ค์ •, ์ƒ์„ธ ์„ค์น˜ CHANGELOG ๋ฒ„์ „๋ณ„ ๋ณ€๊ฒฝ์‚ฌํ•ญ

์šด์˜

  • /health: DB, Redis, pgvector, ์›Œ์ปค ์ƒํƒœ๋ฅผ ์ข…ํ•ฉ ์ ๊ฒ€. ๋ถ€๋ถ„ ์žฅ์•  ์‹œ degraded ์‘๋‹ต.

  • Rate Limiting: API ํ‚ค๋‹น 100/๋ถ„, IP๋‹น 30/๋ถ„. ํ™˜๊ฒฝ๋ณ€์ˆ˜๋กœ ์กฐ์ • ๊ฐ€๋Šฅ.

  • ์›Œ์ปค ๋ณต๊ตฌ: ์ž„๋ฒ ๋”ฉ/ํ‰๊ฐ€ ์›Œ์ปค๊ฐ€ ์—๋Ÿฌ ์‹œ ์ง€์ˆ˜ ๋ฐฑ์˜คํ”„(1sโ†’60s)๋กœ ์ž๋™ ์žฌ์‹œ๋„.

  • Graceful Shutdown: SIGTERM ์‹œ ์ง„ํ–‰ ์ค‘ ์›Œ์ปค ์™„๋ฃŒ ๋Œ€๊ธฐ(30์ดˆ) ํ›„ ์„ธ์…˜ auto-reflect ์‹คํ–‰.

  • OAuth ์—”๋“œํฌ์ธํŠธ: ์ธ์ฆ ์‹คํŒจ ์‹œ WWW-Authenticate ํ—ค๋”๋ฅผ ๋ฐ˜ํ™˜ํ•˜์—ฌ OAuth ํด๋ผ์ด์–ธํŠธ๊ฐ€ ์ž๋™์œผ๋กœ ์ธ์ฆ ํ๋ฆ„์„ ์‹œ์ž‘ํ•  ์ˆ˜ ์žˆ๋‹ค. ์„ธ์…˜ TTL ๊ธฐ๋ณธ๊ฐ’์€ 240๋ถ„์ด๋‹ค.

  • ๋งˆ์ด๊ทธ๋ ˆ์ด์…˜ lint: npm run lint:migrations๋กœ ๋ฒˆํ˜ธ ์ถฉ๋Œ ๋ฐ ๊ทœ์•ฝ ์œ„๋ฐ˜์„ ์ปค๋ฐ‹ ์ „ ๊ฒ€์‚ฌ.

  • ์šด์˜ ๊ฐ€์ด๋“œ: docs/operations/ โ€” LLM provider ์ฒด์ธ, symbolic hard gate, agent worktree, upstream porting ๋“ฑ.

  • ์™ธ๋ถ€ ๋…ธ์ถœ ์ ๊ฒ€: docs/operations/maintenance.md์˜ "์™ธ๋ถ€ ๋…ธ์ถœ ์ ๊ฒ€" ์ ˆ์ฐจ๋กœ listen ์ฃผ์†Œ, ์ธ์ฆ ํ‚ค, Origin allowlist ์ƒํƒœ๋ฅผ ํ™•์ธ.

์•Œ๋ ค์ง„ ์ œํ•œ์‚ฌํ•ญ

  • L1 Redis ์บ์‹œ๋Š” API ํ‚ค ๊ธฐ๋ฐ˜ ๊ฒฉ๋ฆฌ๋งŒ ์ง€์›ํ•œ๋‹ค. multi-agent ํ™˜๊ฒฝ์—์„œ ์—์ด์ „ํŠธ ๊ฐ„ ๊ฒฉ๋ฆฌ๋Š” L2/L3์—์„œ ์ ์šฉ๋œ๋‹ค.

  • ์ž๋™ ํ’ˆ์งˆ ํ‰๊ฐ€๋Š” decision, preference, relation ์œ ํ˜•๋งŒ ๋Œ€์ƒ์ด๋‹ค. fact, procedure, error๋Š” ํ‰๊ฐ€ ํ์—์„œ ์ œ์™ธ๋œ๋‹ค.

  • MEMENTO_ACCESS_KEY๋ฅผ ์„ค์ •ํ•˜์ง€ ์•Š์œผ๋ฉด ์ธ์ฆ์ด ๋น„ํ™œ์„ฑํ™”๋œ๋‹ค. ์™ธ๋ถ€ ๋…ธ์ถœ ํ™˜๊ฒฝ์—์„œ๋Š” ๋ฐ˜๋“œ์‹œ ์„ค์ •ํ•  ๊ฒƒ.

  • ALLOWED_ORIGINS โ€” ๋ธŒ๋ผ์šฐ์ € ๊ธฐ๋ฐ˜ MCP ํด๋ผ์ด์–ธํŠธ ํ™”์ดํŠธ๋ฆฌ์ŠคํŠธ. ๋ฏธ์„ค์ • ์‹œ ๋ชจ๋“  Origin์„ ํ—ˆ์šฉํ•œ๋‹ค. ์™ธ๋ถ€ ๋…ธ์ถœ ํ™˜๊ฒฝ์—์„œ๋Š” MCP_STRICT_ORIGIN=true์™€ ํ•จ๊ป˜ ์‹ค์ œ ์‚ฌ์šฉํ•˜๋Š” ๋ธŒ๋ผ์šฐ์ € Origin๋งŒ ๋“ฑ๋กํ•  ๊ฒƒ. ๋ฐ์Šคํฌํƒ‘/CLI/IDE ํ™•์žฅ(Claude Code, Cursor, Windsurf, Continue, Cline, Zed, gemini CLI ๋“ฑ)์€ Origin ํ—ค๋”๋ฅผ ๋ณด๋‚ด์ง€ ์•Š์œผ๋ฏ€๋กœ ํ™”์ดํŠธ๋ฆฌ์ŠคํŠธ ๋ถˆํ•„์š”. ๋ธŒ๋ผ์šฐ์ € ํ›„๋ณด: claude.ai, claude.com, chatgpt.com, chat.openai.com, copilot.microsoft.com, gemini.google.com, aistudio.google.com, www.perplexity.ai, cursor.com, codeium.com, windsurf.com, sourcegraph.com, typingmind.com (์‹ค์ œ ํ˜ธ์ถœํ•˜๋Š” ๊ฒƒ๋งŒ ์„ ๋ณ„).

  • ADMIN_ALLOWED_ORIGINS โ€” Admin UI ํ˜ธ์ถœ origin ํ™”์ดํŠธ๋ฆฌ์ŠคํŠธ. ๋ฏธ์„ค์ • ์‹œ ๋ชจ๋“  Origin์„ ํ—ˆ์šฉํ•œ๋‹ค. ์™ธ๋ถ€ ๋…ธ์ถœ ํ™˜๊ฒฝ์—์„œ๋Š” ๊ด€๋ฆฌ ์ฝ˜์†” Origin์„ ๋ช…์‹œํ•˜๊ฑฐ๋‚˜ ๋ฆฌ๋ฒ„์Šค ํ”„๋ก์‹œ/๋ฐฉํ™”๋ฒฝ์—์„œ ์ ‘๊ทผ์„ ์ œํ•œํ•  ๊ฒƒ.

  • TRUST_PROXY_HOPS โ€” ์‹ ๋ขฐ ๊ฐ€๋Šฅํ•œ ๋ฆฌ๋ฒ„์Šค ํ”„๋ก์‹œ hop ์ˆ˜. ๋ฏธ์„ค์ • ์‹œ ๊ธฐ์กด ๋™์ž‘ ์œ ์ง€(XFF ์ฒซ ํ•ญ๋ชฉ). ์ง์ ‘ ๋…ธ์ถœ ์‹œ 0, ๋‹จ์ผ ํ”„๋ก์‹œ ๋’ค์—์„œ๋Š” 1.

  • OAUTH_TRUSTED_ORIGINS โ€” ๋™์˜ ์ž๋™ ์Šน์ธ ๋Œ€์ƒ origin ํ™”์ดํŠธ๋ฆฌ์ŠคํŠธ. ๋™์ผ origin์—์„œ ์—ฌ๋Ÿฌ ์•ฑ์„ ํ˜ธ์ŠคํŒ…ํ•˜๋ฉด OAUTH_ALLOWED_REDIRECT_URIS์˜ ์ „์ฒด URI ๋งค์นญ ์‚ฌ์šฉ์„ ๊ถŒ์žฅ.

๊ธฐ์ˆ  ์Šคํƒ

  • Node.js 20+

  • PostgreSQL 14+ (pgvector ํ™•์žฅ)

  • Redis 6+ (์„ ํƒ)

  • OpenAI Embedding API (์„ ํƒ) ๋˜๋Š” EMBEDDING_PROVIDER=transformers (๋กœ์ปฌ ์ €๋น„์šฉ ๋ชจ๋“œ)

  • garu-ko / natural PorterStemmer / @node-rs/jieba / kuromoji (๋กœ์ปฌ ํ˜•ํƒœ์†Œ ๋ถ„์„, ์–ธ์–ด๋ณ„ CPU ๋ผ์šฐํŒ…; MEMENTO_MORPHEME_TOKENIZER=local ๊ธฐ๋ณธ)

  • Gemini CLI / Codex CLI / GitHub Copilot CLI (ํ’ˆ์งˆ ํ‰๊ฐ€, ์ž๋™ reflect; ์„ ํƒ, LLM_PRIMARY / LLM_FALLBACKS๋กœ ์ฒด์ธ ๊ตฌ์„ฑ)

  • @huggingface/transformers + ONNX Runtime (NLI ๋ชจ์ˆœ ๋ถ„๋ฅ˜ + ๋กœ์ปฌ ์ž„๋ฒ ๋”ฉ, CPU ์ „์šฉ)

  • MCP Protocol 2025-11-25

PostgreSQL๋งŒ ์žˆ์œผ๋ฉด ํ•ต์‹ฌ ๊ธฐ๋Šฅ์ด ๋™์ž‘ํ•œ๋‹ค. Redis๋ฅผ ์ถ”๊ฐ€ํ•˜๋ฉด L1 ์บ์Šค์ผ€์ด๋“œ ๊ฒ€์ƒ‰๊ณผ SessionActivityTracker๊ฐ€ ํ™œ์„ฑํ™”๋˜๊ณ , OpenAI API ๋˜๋Š” EMBEDDING_PROVIDER=transformers๋ฅผ ์ถ”๊ฐ€ํ•˜๋ฉด L3 ์‹œ๋งจํ‹ฑ ๊ฒ€์ƒ‰๊ณผ ์ž๋™ ๋งํฌ๊ฐ€ ํ™œ์„ฑํ™”๋œ๋‹ค.

๋งŒ๋“ค๊ฒŒ ๋œ ๊ณ„๊ธฐ

์ ‘๊ธฐ/ํŽผ์น˜๊ธฐ ์‹ค๋ฌด์—์„œ AI๋ฅผ ์“ฐ๋ฉด์„œ ๋งค์ผ ๊ฐ™์€ ๋งฅ๋ฝ์„ ๋ฐ˜๋ณต ์„ค๋ช…ํ•˜๋Š” ๋น„ํšจ์œจ์„ ๋А๊ผˆ๋‹ค. ์‹œ์Šคํ…œ ํ”„๋กฌํ”„ํŠธ์— ๋ฉ”๋ชจ๋ฅผ ๋„ฃ๋Š” ๋ฐฉ๋ฒ•๋„ ์จ๋ดค์ง€๋งŒ ํ•œ๊ณ„๊ฐ€ ๋ช…ํ™•ํ–ˆ๋‹ค. ํŒŒํŽธ ์ˆ˜๊ฐ€ ๋Š˜์–ด๋‚˜๋ฉด ๊ด€๋ฆฌ๊ฐ€ ์•ˆ ๋˜๊ณ , ๊ฒ€์ƒ‰์ด ์•ˆ ๋˜๊ณ , ์˜ค๋ž˜๋œ ์ •๋ณด์™€ ์ƒˆ ์ •๋ณด๊ฐ€ ์ถฉ๋Œํ–ˆ๋‹ค.

์ด๋ฏธ ์„ค๋ช…ํ•œ ๊ฒƒ, ์ด๋ฏธ ์„ธํŒ…ํ•œ ๊ฒƒ์„ ๋ฌดํ•œํžˆ ๋ฐ˜๋ณตํ•˜๊ฒŒ ๋งŒ๋“œ๋Š” ๊ฒƒ์ด ๊ฐ€์žฅ ํฐ ๋ฌธ์ œ์˜€๋‹ค. ์ธ์ฆ ์ •๋ณด๊ฐ€ ์—†๋‹ค๊ณ  ํ•ด์„œ ๋ณด๋ฉด ์žˆ๊ณ , ์„ธํŒ… ์•ˆ ๋ผ ์žˆ๋‹ค๊ณ  ํ•ด์„œ ํŒŒ์ผ์„ ์ง์ ‘ ์—ด์–ด๋ณด๋ฉด ๋‹ค ๋ผ ์žˆ๋‹ค. ์ฒ ์ €ํ•˜๊ฒŒ ๋…ผํŒŒํ•ด์„œ ๋ง ์ž˜ ๋“ฃ๊ฒŒ ํ•ด ๋ด์•ผ ๊ทธ๋•Œ๋ฟ์ด๋‹ค. ์„ธ์…˜์„ ๋‹ค์‹œ ์‹œ์ž‘ํ•˜๋ฉด ๊ฐ™์€ ์ผ์ด ๋˜ ๋ฐ˜๋ณต๋œ๋‹ค. ๋ช…๋ฌธ๋Œ€๋ฅผ ์ˆ˜์„ ์กธ์—…ํ–ˆ์ง€๋งŒ ๋งค์ผ ๋‡Œ๊ฐ€ ๋ฆฌ์…‹๋˜๋Š” ์‹ ์ž…์‚ฌ์›์˜ ๊ต์œก๋‹ด๋‹น์ž๊ฐ€ ๋œ ๊ธฐ๋ถ„์ด์—ˆ๋‹ค.

"์•ผ ๋„ˆ ๋ฏธ์ •์ด ๊ธฐ์–ต๋‚˜๋ƒ" -- ๋‹จ์„œ ์—†์ด๋Š” ์•„๋ฌด๊ฒƒ๋„ ๋– ์˜ค๋ฅด์ง€ ์•Š์ง€๋งŒ, "์ดˆ๋“ฑํ•™๊ต 1ํ•™๋…„ ๋•Œ ์ง๊ถ" ํ•œ๋งˆ๋””๋ฉด ์ง€์šฐ๊ฐœ ๋นŒ๋ ค์คฌ๋˜ ์ผ๊นŒ์ง€ ์ค„์ค„์ด ๋– ์˜ค๋ฅธ๋‹ค. AI๋„ ๋งˆ์ฐฌ๊ฐ€์ง€๋‹ค. ์–ด์ œ ํ•ด๊ฒฐํ•œ ๋ฒ„๊ทธ, ์ง€๋‚œ์ฃผ ๋‚ด๋ฆฐ ๊ฒฐ์ •, ์„ ํ˜ธํ•˜๋Š” ์ฝ”๋”ฉ ์Šคํƒ€์ผ. ๋งค ์„ธ์…˜ ๋ฆฌ์…‹ ๋Œ€์‹ , Memento๊ฐ€ ๊ธฐ์–ตํ•ด๋‘”๋‹ค.

์ด ๊ณ ์ถฉ์„ ํ•ด์†Œํ•˜๊ธฐ ์œ„ํ•ด ๊ธฐ์–ต์„ ์›์ž ๋‹จ์œ„๋กœ ๋ถ„ํ•ดํ•˜๊ณ , ๊ณ„์ธต์ ์œผ๋กœ ๊ฒ€์ƒ‰ํ•˜๊ณ , ์‹œ๊ฐ„์— ๋”ฐ๋ผ ์ž์—ฐ์Šค๋Ÿฝ๊ฒŒ ๋ง๊ฐํ•˜๋Š” ์‹œ์Šคํ…œ์„ ์„ค๊ณ„ํ–ˆ๋‹ค. ์ธ๊ฐ„์ด ๋ง๊ฐ์˜ ๋™๋ฌผ์ธ ๊ฒƒ์ฒ˜๋Ÿผ, ์ด ์‹œ์Šคํ…œ์€ "์ ์ ˆํ•œ ๋ง๊ฐ"์„ ํฌํ•จํ•œ ๊ธฐ์–ต์„ ์ง€ํ–ฅํ•œ๋‹ค.

๊ทธ๋ฆฌ๊ณ  ๊ฑฐ๊ธฐ์„œ ๋ฉˆ์ถ”์ง€ ์•Š๋Š”๋‹ค. ํ”ผ๋“œ๋ฐฑ์ด ๋ˆ„์ ๋ ์ˆ˜๋ก ์—ฐ๊ฒฐ์ด ๊ฐ•ํ•ด์ง€๊ณ  ์•ฝํ•œ ๋งํฌ๋Š” ์‚ฌ๋ผ์ง„๋‹ค. ๊ฐ™์€ ๊ฒฝํ—˜์ด ๋ฐ˜๋ณต๋ ์ˆ˜๋ก ํŒจํ„ด์ด ์ถ”์ƒํ™”๋œ๋‹ค. ์„ธ์…˜ ๊ฐ„ ์—ํ”ผ์†Œ๋“œ๊ฐ€ ์ด์–ด์งˆ์ˆ˜๋ก ๋งฅ๋ฝ์ด ์ด์•ผ๊ธฐ๊ฐ€ ๋œ๋‹ค. ๋„์„œ๊ด€์„ ์ง“๋Š” ๊ฒŒ ์•„๋‹ˆ๋‹ค. ๊ฒฝํ—˜์œผ๋กœ ์„ฑ์žฅํ•˜๋Š” AI๋ฅผ ๋งŒ๋“ค๊ณ  ์‹ถ์—ˆ๋‹ค.

๊ธฐ์–ต์€ ์ง€๋Šฅ์˜ ์ „์ œ๊ฐ€ ์•„๋‹ˆ๋‹ค. ๊ธฐ์–ต์€ ์ง€๋Šฅ์˜ ์กฐ๊ฑด์ด๋‹ค. ์ฒด์Šค๋ฅผ ๋‘๋Š” ๋ฐฉ๋ฒ•์„ ์•Œ์•„๋„, ์–ด์ œ ์ง„ ๊ฒŒ์ž„์„ ๊ธฐ์–ตํ•˜์ง€ ๋ชปํ•˜๋ฉด ๊ฐ™์€ ์ˆ˜๋ฅผ ๋˜ ๋‘”๋‹ค. ๋ชจ๋“  ์–ธ์–ด๋ฅผ ๊ตฌ์‚ฌํ•ด๋„, ์–ด์ œ ๋‚˜๋ˆˆ ๋Œ€ํ™”๋ฅผ ๊ธฐ์–ตํ•˜์ง€ ๋ชปํ•˜๋ฉด ๋งค๋ฒˆ ์ฒ˜์Œ ๋งŒ๋‚˜๋Š” ์‚ฌ๋žŒ์ด ๋œ๋‹ค. ์ˆ˜์‹ญ์–ต ๊ฐœ์˜ ํŒŒ๋ผ๋ฏธํ„ฐ๋กœ ์„ธ์ƒ ๋ชจ๋“  ์ง€์‹์„ ๋‹ด์•„๋„, ๋‹น์‹ ๊ณผ ํ•จ๊ป˜ํ•œ ์–ด์ œ๋ฅผ ๊ธฐ์–ตํ•˜์ง€ ๋ชปํ•˜๋ฉด ๋‚ฏ์„  ๋ฐ•์‹๊ฐ€์ผ ๋ฟ์ด๋‹ค.

๊ธฐ์–ต์ด ์žˆ์–ด์•ผ ๊ด€๊ณ„๊ฐ€ ์žˆ๋‹ค. ๊ด€๊ณ„๊ฐ€ ์žˆ์–ด์•ผ ์‹ ๋ขฐ๊ฐ€ ์žˆ๋‹ค.

๊ธฐ์–ต์€ ์‚ฌ๋ผ์ง€์ง€ ์•Š๋Š”๋‹ค. ๋‹ค๋งŒ cold tier๋กœ ๋‚ด๋ ค๊ฐˆ ๋ฟ์ด๋‹ค. ๊ทธ๋ฆฌ๊ณ  ์ถฉ๋ถ„ํžˆ ์˜ค๋ž˜ ๋ฐฉ์น˜๋œ cold ํŒŒํŽธ์€ ๋‹ค์Œ consolidate ์‚ฌ์ดํด์—์„œ ์†Œ๋ฉธํ•œ๋‹ค. ์ด๊ฒƒ์€ ์„ค๊ณ„์ด์ง€ ๋ฒ„๊ทธ๊ฐ€ ์•„๋‹ˆ๋‹ค. ์“ธ๋ชจ์—†์–ด์ง„ ๊ธฐ์–ต์€ ์ž๋ฆฌ๋ฅผ ๋น„์›Œ์•ผ ํ•œ๋‹ค. ์•„์šฐ๊ตฌ์Šคํ‹ฐ๋ˆ„์Šค์˜ ๊ถ์ „์—๋„ ์ฐฝ๊ณ  ์ •๋ฆฌ๋Š” ํ•„์š”ํ•˜๋‹ค.

๋ฉ์ฒญํ•œ ๊ฑธ๋กœ ์œ ๋ช…ํ•œ ๊ธˆ๋ถ•์–ด์ƒˆ๊ธฐ๋„ ๋ช‡ ๋‹ฌ์„ ๊ธฐ์–ตํ•œ๋‹ค.

์ด์ œ ๋‹น์‹ ์˜ AI๋„ ๊ทธ๋ ‡๋‹ค.

License

Apache 2.0

Made by Jinho Choi ย |ย  Buy me a coffee