ERINYS — AI 에이전트를 위한 반사적 기억

🇯🇵 日本語版 / Japanese

존재했던 기억으로부터, 존재하지 않았던 기억까지 만들어냅니다.

AI 에이전트의 기억 시스템은 항상 인간의 기억을 모방해 왔습니다. 단기, 장기, 일화적, 의미적 기억 등 교과서적인 분류를 구현에 그대로 적용했습니다.

무언가 항상 어색했습니다.

인간은 망각합니다. 하지만 기존의 기억 시스템은 그렇지 않습니다. 기억은 끝없이 증식하며, 오래된 사실을 최신 정보와 동일한 비중으로 제공합니다. 인간은 "잠깐, 아까는 다르게 말하지 않았어?"라고 알아차리지만, 기억 시스템은 조용히 덮어씁니다. 인간은 서로 관련 없는 두 경험을 연결하며 "아, 여기서 써먹을 수 있겠네"라고 생각하지만, 기억 시스템은 단순히 저장하고 검색할 뿐입니다.

모방해야 했던 것은 기억의 분류 체계가 아니었습니다. 바로 그 행동 방식이었습니다.

그 불편함이 ERINYS를 탄생시켰습니다.

ERINYS는 감시견입니다. 기억하고, 잊고, 질문하고, 물어뜯습니다.

ERINYS가 특별한 이유

망각. 대부분의 기억 시스템은 축적만 합니다. ERINYS는 에빙하우스의 망각 곡선에 따라 시간이 지남에 따라 기억을 감쇠시킵니다. 오래된 노이즈는 가라앉고, 자주 접근하는 지식은 떠오릅니다. 검색 결과는 수동 관리 없이도 관련성을 유지합니다.

증류(Distillation). 특정 버그 수정("JWT httpOnly 플래그가 누락됨")은 자동으로 세 가지 계층을 생성합니다: 구체적 사실 → 재사용 가능한 패턴("새 엔드포인트에는 보안 체크리스트가 필요함") → 보편적 원칙("보안 기본값은 옵트인 없이 안전해야 함"). 다른 어떤 기억 시스템도 이런 기능을 제공하지 않습니다.

꿈의 주기(Dream Cycle). 두 개의 기억이 LLM에 입력됩니다: "연관성이 있는가?" 후보 쌍은 의미론적 유사성에 의해 선택됩니다 — 관련성이 있을 만큼 가깝고(코사인 > 0.65), 중복되지 않을 만큼 멉니다(< 0.90). cron을 통해 밤사이에 예약되어, 당신이 미처 생각하지 못한 연결 고리를 찾아냅니다. 마법은 없습니다. 그저 대규모 자동 노트 비교일 뿐입니다.

설계 철학

기억에는 계층이 있습니다

모든 기억이 동일하지는 않습니다. ERINYS는 지식을 추상화 수준에 따라 구성합니다:

• 구체적(Concrete) — 무슨 일이 일어났는가. "/api/auth에서 JWT httpOnly 플래그가 누락되었다."

• 추상적(Abstract) — 사실로부터 얻은 패턴. "새 API 엔드포인트에는 보안 헤더 체크리스트가 필요하다."

• 메타(Meta) — 패턴으로부터 얻은 원칙. "보안 기본값은 수동 옵트인 없이 안전해야 한다."

단 하나의 버그 수정이 증류 과정을 통해 이 세 가지를 모두 생성합니다. 메타 계층은 프로젝트와 기술 스택을 넘나드는 원칙들을 축적합니다.

망각은 기능입니다

모든 기억은 시간이 지남에 따라 감쇠하는 강도 점수를 가집니다. 6개월 전에 저장된 기억은 어제 저장된 기억보다 낮은 순위를 가집니다. 자주 접근하는 기억은 감쇠에 저항합니다 — 반복적인 검색이 기억을 강화합니다.

강도가 임계값 아래로 떨어지면, 해당 기억은 정리(pruning) 후보가 됩니다. 데이터베이스는 가볍게 유지되고, 검색은 관련성을 유지합니다.

사실은 변합니다. 역사는 사라지지 않아야 합니다

정보가 업데이트될 때("AWS에서 GCP로 이전했다") — ERINYS는 덮어쓰지 않습니다. 대신 대체 체인(supersede chain)을 생성합니다: 이전 사실은 대체된 것으로 표시되지만 보존됩니다. "3월에는 우리가 무엇을 믿었지?"라고 물으면 당시에는 사실이었던 답변을 얻을 수 있습니다.

모순은 포착되어야 합니다

기억에 "PostgreSQL 사용"과 "SQLite 사용"이 모두 포함되어 있다면, ERINYS는 충돌을 감지합니다. 조용히 전환하는 대신, 에이전트는 질문합니다: "이전에 PostgreSQL을 선택하셨는데, 요구사항이 변경되었나요?"

검색은 키워드가 아닌 의미를 찾습니다

두 가지 검색이 동시에 실행되어 결과를 융합합니다:

• 키워드 검색(FTS5) — 정확한 용어 일치.

• 벡터 검색(sqlite-vec) — 의미론적 유사성. "authentication"은 "login", "JWT", "session tokens"를 찾습니다.

결과는 RRF(Reciprocal Rank Fusion)를 통해 병합됩니다. 둘 다에서 높은 순위일수록 가장 높은 점수를 받습니다.

모든 것은 로컬에 머뭅니다

단일 SQLite 파일. 클라우드 API 없음. API 키 없음. 구독 없음. 오프라인 가능. 에이전트의 기억은 절대 당신의 기기를 떠나지 않습니다.

사용 사례

1. 코딩 에이전트를 위한 세션 간 기억

# Agent saves a learning after fixing a bug
erinys_save(
  title="Fixed JWT httpOnly flag missing",
  content="Cookie was accessible via JS. Added httpOnly: true, secure: true, sameSite: strict.",
  type="bugfix",
  project="my-app"
)

# Next week, similar task — agent searches memory
erinys_search(query="authentication cookie security", project="my-app")
# → Returns the JWT fix with relevance score

2. 모순 탐지

erinys_save(title="Database choice", content="Using SQLite for simplicity", project="my-app")
erinys_conflict_check(observation_id=42)
# → "⚠️ Conflicts with #18: 'Using PostgreSQL for production reliability'"

3. 꿈의 주기 — 야간 지식 합성

erinys_dream(max_collisions=10)
# Picks memory pairs in the "sweet spot" (cosine 0.65–0.90)
# Memory A: "RTK reduces token usage by 60-90%"
# Memory B: "Bootstrap Gate takes 3 seconds due to multiple script calls"
# → Insight: "Apply RTK prefix to Bootstrap Gate scripts to reduce overhead"

4. 시간적 쿼리

erinys_timeline(query="deployment target", as_of="2026-03-01")
# → "AWS EC2 (decided 2026-02-15)"

erinys_timeline(query="deployment target", as_of="2026-04-01")
# → "GCP Cloud Run (superseded AWS on 2026-03-20)"

5. 지식 증류

erinys_save(title="Forgot CORS headers on new endpoint", type="bugfix", ...)
erinys_distill(observation_id=50, level="meta")
# → concrete: "CORS headers missing on /api/v2/users endpoint"
# → abstract: "New API endpoints need a CORS review checklist"
# → meta:     "Security concerns should be opt-out, not opt-in"

6. Obsidian 내보내기

erinys_export(format="markdown")
# → Generates .md files with [[wikilinks]]
# Drop into Obsidian → instant knowledge graph

빠른 시작

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run as MCP server (stdio)
python -m erinys_memory.server

# Run tests
PYTHONPATH=src pytest tests/ -v

MCP 설정

Claude Desktop / Claude Code

{
  "mcpServers": {
    "erinys": {
      "command": "/path/to/ERINYS-mem/.venv/bin/python3",
      "args": ["-m", "erinys_memory.server"],
      "env": {
        "ERINYS_DB_PATH": "~/.erinys/memory.db"
      }
    }
  }
}

Gemini (Antigravity)

~/.gemini/antigravity/settings.json의 mcpServers 아래에 추가하세요:

{
  "erinys": {
    "command": "/path/to/ERINYS-mem/.venv/bin/python3",
    "args": ["-m", "erinys_memory.server"],
    "env": {
      "ERINYS_DB_PATH": "~/.erinys/memory.db"
    }
  }
}

환경 변수

도구 (25)

핵심

• erinys_save — 관찰 내용 저장 (topic_key upsert 포함)

• erinys_get — ID로 가져오기 (전체 내용, 잘림 없음)

• erinys_update — 부분 업데이트

• erinys_delete — FK 캐스케이드와 함께 삭제

• erinys_search — RRF 하이브리드 검색 (FTS5 + 벡터)

• erinys_save_prompt — 사용자 프롬프트 저장

• erinys_recall — 최근 관찰 내용

• erinys_context — 세션 컨텍스트 회상

• erinys_export — Obsidian 호환 마크다운 내보내기

• erinys_backup — SQLite 백업

• erinys_stats — 데이터베이스 통계

그래프

• erinys_link — 타입이 지정된 엣지 생성

• erinys_traverse — BFS 그래프 탐색

• erinys_prune — 약하거나 감쇠된 엣지 정리

시간적

• erinys_reinforce — 관찰 강도 강화

• erinys_supersede — 관찰 내용 버전 관리

• erinys_timeline — 타임스탬프 기준 쿼리

• erinys_conflict_check — 모순 탐지

꿈의 주기

• erinys_collide — LLM을 통해 두 관찰 내용 충돌시키기

• erinys_dream — 배치 충돌 주기

증류

• erinys_distill — 3단계 세분성 추상화 (구체적 → 추상적 → 메타)

배치 및 평가

• erinys_batch_save — 자동 연결을 포함한 대량 저장

• erinys_eval — LOCOMO 기반 품질 지표

세션

• erinys_session_start — 세션 시작

• erinys_session_end — 요약과 함께 세션 종료

• erinys_session_summary — 구조화된 요약 저장

ERINYS 비교

요약 — 대부분의 메모리 서버는 저장하고 검색합니다. ERINYS는 또한 잊고, 증류하고, 꿈을 꿉니다.

아키텍처

┌──────────────────────────┐
│     FastMCP Server       │  25 tools, unified envelope
├──────────────────────────┤
│  search.py  │ graph.py   │  RRF hybrid │ typed edges
│  decay.py   │ session.py │  Ebbinghaus │ lifecycle
│  temporal.py│collider.py │  versioning │ cross-pollination
│  distill.py │ db.py      │  abstraction│ SQLite + vec
├──────────────────────────┤
│  embedding.py            │  fastembed (BAAI/bge-small-en-v1.5)
├──────────────────────────┤
│  SQLite + FTS5 + vec0    │  Local-first, no network at runtime
└──────────────────────────┘

로드맵

• [ ] Dream Daemon — 꿈의 주기의 백그라운드 자동 실행

• [x] 저장 시 자동 증류 — 저장할 때마다 3단계 세분성 증류 트리거

• [ ] 자동 정리 — DB가 크기 임계값을 초과할 때 감쇠된 관찰 내용 GC

• [ ] Cron 지원 CLI — 예약된 야간 합성을 위한 erinys dream --max 10

• [ ] PyPI 패키지 — pip install erinys-memory

• [ ] 다중 에이전트 지원 — 에이전트 ID별 범위 지정 메모리

라이선스

MIT