AI 코딩 에이전트의 영구 메모리

AI 코딩 에이전트를 위한 영속 메모리

한 뇌. 로컬 또는 클라우드. 에이전트 무관, 단일 바이너리, 제로 의존성.

설치 • Engram Cloud • 에이전트 설정 • 코드베이스 가이드 • 아키텍처 • 플러그인 • 기여 • 전체 문서

engram/ˈen.ɡræm/

—신경과학: 뇌의 물리적 기억 흔적.

AI 코딩 에이전트는 세션이 끝나면 모든 것을 잊어버립니다. Engram 은 그에게 뇌를 줍니다.

CLI, HTTP API, MCP 서버, 인터랙티브 TUI 를 통해 노출된 Go 바이너리와 SQLite + FTS5全文 검색을 제공합니다. MCP 을 지원하는 모든 에이전트와 함께 작동합니다 — Claude Code, OpenCode, Gemini CLI, Codex, VS Code (Copilot), Antigravity, Cursor, Windsurf, 또는 그 외의 것들.

Agent (Claude Code / OpenCode / Gemini CLI / Codex / VS Code / Antigravity / ...)
↓ MCP stdio
Engram (single Go binary)
...

brew install gentleman-programming/tap/engram

Windows, Linux, 기타 설치 방법 → docs/INSTALLATION.md

에이전트	한 줄 명령어
Claude Code	claude plugin marketplace add Gentleman-Programming/engram && claude plugin install engram
...

완전한 에이전트별 설정, 메모리 프로토콜, 컴팩션 생존 → docs/AGENT-SETUP.md

그만. Node.js 없음, Python 없음, Docker 없음. 한 바이너리, 한 SQLite 파일.

1. 에이전트가 중요한 작업을 완료함 (버그 수정, 아키텍처 결정 등)
2. 에이전트가 mem_save 를 호출 → 제목, 유형, 무엇을/왜/어디에서/배운 것
3. Engram 이 FTS5 인덱싱과 함께 SQLite 에 영구 저장
...

세션 라이프사이클, 주제 키, 메모리 위생에 대한 자세한 정보 → docs/ARCHITECTURE.md

카테고리	도구
저장 및 업데이트
mem_save, mem_update, mem_delete, mem_suggest_topic_key
검색 및 검색
mem_search, mem_context, mem_timeline, mem_get_observation
세션 라이프사이클
mem_session_start, mem_session_end, mem_session_summary
충돌 표면화
mem_judge, mem_compare
유틸리티
mem_save_prompt, mem_stats, mem_capture_passive, mem_merge_projects, mem_current_project, mem_doctor

파라미터가 있는 전체 도구 참조 → DOCS.md#mcp-tools-19-tools

engram tui

네비게이션: j/k
vim 키, Enter

드릴링을 위해, /

검색을 위해, Esc

뒤로. Catppuccin Mocha 테마.

기계를 넘어 메모리를 공유합니다. 압축된 조각을 사용 — 병합 충돌 없음, 거대한 파일 없음.

로컬 SQLite 는 진실의 원천입니다. 클라우드 통합은 선택적 복제입니다.

engram sync # 새 메모리를 압축된 조각으로 내보내기
git add .engram/ && git commit -m "sync engram memories"
engram sync --import # 다른 기계에서: 새 조각 가져오기
...

완전한 동기화 문서 → DOCS.md

클라우드가 선택적입니다. 로컬 SQLite 는 권위 있는; 클라우드는 복제/공유 액세스 만입니다.

추천 첫 번째 경로 (로컬 스모크):

docker compose -f docker-compose.cloud.yml up -d
engram cloud config --server http://127.0.0.1:18080
engram cloud enroll smoke-project
...

클라우드 모드는 항상 프로젝트 범위 (--project 필수; engram sync --cloud --all 의 의도된 차단).
알려진 복구 가능한 클라우드 동기화/업셋/규격화 실패는 원래 오류를 표시하고 명시적인 doctor
/repair 흐름을 추천합니다; Engram 은 동기화 또는 자동동기화에서 자동으로 복구 적용하지 않습니다.
차단된 클라우드 동기화를 위해, transport_failed, 또는 레거시 세션 디렉터리 복구를 위해 Engram Cloud Troubleshooting 을 참조하세요.
클라우드 동기화가 doctor/repair 후에도 차단되면 구제 도구 다운로드 및 권장 내보내기 행 복구 실행:

tools/repair-missing-session-directory.sh --apply --interactive --fix-exported <project>
ingram sync --cloud --project <project>

--fix-exported

local exported sessions[].directory
and observations[]
required fields that can still break the final push after doctor
reports ready. For sequential legacy sync_mutations
blockers, use tools/repair-missing-session-directory.sh --apply --interactive --all <project>
.

After upgrading engram while an MCP client is already running:

engram setup claude-code
Then restart Claude Code so it reloads the Engram MCP subprocess and refreshed hook/config files. Updating the engram
binary on disk does not replace an already-running stdio MCP process.

Upgrade flow for existing local databases (diagnose → repair → bootstrap → status):

ingram cloud upgrade doctor --project smoke-project # read-only readiness check
engram cloud upgrade repair --project smoke-project --dry-run
engram cloud upgrade repair --project smoke-project --apply
...

See DOCS.md — Cloud upgrade flow for the full state machine.

For authenticated mode, upgrade flow, dashboard behavior, reason codes, and full runtime/env details:

• Engram Cloud docs landing
• Engram Cloud quickstart
• DOCS.md — Cloud CLI reference
• DOCS.md — Cloud Autosync

Try the new memory-conflict-surfacing features in complete isolation from your existing engram setup. Docker uses non-default ports + a separate data dir + a beta-only token, so your prod cloud and ~/.engram/
are untouched. Cleanup is one command.

What's in the beta:

• 🔄 Cloud sync of conflict relations cross-machine
• 🔍
  engram conflicts
  CLI + HTTP API for retroactive audit + scan - 🧠
  --semantic
  scan that usesyour existing Claude Code or OpenCode CLIto judge FTS5 conflict candidates with LLM reasoning —$0 if you're on a Pro/Max/Plus subscription

git clone https://github.com/Gentleman-Programming/engram.git engram-beta-repo
cd engram-beta-repo && git checkout feat/memory-conflict-surfacing-cloud-sync
docker compose -f docker-compose.beta.yml up -d
...

1️⃣ Phase 1 — Conflict detection on save (sanity)

./engram-beta save \
"Use Clean Architecture" \
"Layers: entities, use cases, adapters." \
...

✅ Second save returns candidates[]
with the first memory's id.

2️⃣ Phase 2 — Cloud sync of relations cross-machine

./engram-beta cloud enroll beta-test
./engram-beta sync --cloud --project beta-test
./engram-beta cloud status
...

✅ The "second machine" sees memories synced from the first.

3️⃣ Phase 3 — Admin CLI + HTTP API

./engram-beta conflicts list --project beta-test
./engram-beta conflicts stats --project beta-test
./engram-beta conflicts scan --project beta-test --dry-run
...

✅ List/scan/stats return sensible data.

4️⃣ Phase 4 — Semantic LLM-judge (the killer feature) 🎯

export ENGRAM_AGENT_CLI=claude # or opencode
./engram-beta conflicts scan --project beta-test --semantic --apply \
--max-semantic 5 --concurrency 3 --yes

✅ Your agent's LLM judges semantic similarity. $0 if on a subscription.

5️⃣ The case where FTS5 finds a candidate, then the LLM judges meaning

Lexically related candidate titles with a semantic conflict:

./engram-beta save \
"Use Postgres for the user database" \
"Postgres 15 is our SQL store for users." \
...

✅ FTS5 supplies the candidate pair through shared title terms like user
/ database

LLM 은 supersedes

/ conflicts_with

. --semantic

을 판단합니다.

--semantic

은 본래적으로 완전히 다른 어휘적 쌍을 스스로 발견하지 못합니다.

docker compose -f docker-compose.beta.yml down -v
rm -rf /tmp/engram-beta-data /tmp/engram-beta-data-2 ./engram-beta

프로덕션용 엔그램 (Engram) 은 완전히 무해하게 유지됩니다.

→ beta-phase-2-3-4 의 문제점 보고:

Command	Description
engram setup [agent]
Agent 통합 설치
engram serve [port]
HTTP API 시작 (기본값: 7437)
engram mcp [--tools=PROFILE]
MCP 서버 시작 (stdio 전송)
engram tui
터미널 UI 실행
engram search <query>
기억 검색
engram save <title> <msg>
기억 저장
engram timeline <obs_id>
시간순 맥락
engram context [project]
최근 세션 맥락
engram stats
기억 통계
engram export [file]
JSON 로 내보내기
engram import <file>
JSON 에서 가져오기
engram sync
Git 동기화 (내보내기/가져오기)
engram cloud <subcommand>
클라우드 설정/상태/등록 참여 + 클라우드 런타임 (serve)
`engram projects list	consolidate
프로젝트 이름 관리
engram obsidian-export
Obsidian 저장소로 내보내기 (베타)
engram version
버전 표시

Full CLI 와 모든 플래그 → docs/ARCHITECTURE.md#cli-reference

Doc	Description
Installation	모든 설치 방법 + 플랫폼 지원
...

Dashboard 기여자: internal/cloud/dashboard/

에 있는 .templ

파일을 수정할 경우, 커밋 전에 make templ

을 실행하여 재생성해야 합니다. DOCS.md — Dashboard 템플릿 재생성 참조.

MIT

claude-mem 에서 영감을 받았지만, 에이전트 무관 (agent-agnostic), 단순하고 다르게 구축되었습니다.