ai-memory
- 추천0
- GitHub 별16K
- 메모리라이선스MIT
코딩 에이전트용 장기 기억. Claude Code·Codex·Cursor 등 20여 개가 마크다운 위키 기억과 핸드오프를 함께 써요
설치 방법은 설치 탭에 정리했어요.
설명

AI 코딩 에이전트를 위한 장기 기억. 작업 도중 Claude Code를 종료하고 같은 폴더에서 OpenAI Codex를 켜도, 아키텍처 · 실패한 시도 · 남은 질문을 다시 설명하지 않고 이어서 작업할 수 있어요.
웹사이트: aimemory.sh
ai-memory를 쓰는 이유
코딩 에이전트에는 이미 기억 기능이 있을 거예요. Claude Code는 자기 노트를 남기고, Cursor도 일부를 기억하며, 다른 플랫폼도 계속 추가하고 있죠. 하지만 한계는 모두 같습니다. 노트가 한 컴퓨터에 있고, 한 에이전트에만 속하며, 도구를 바꾸거나 팀원에게 넘기면 시야에서 사라집니다. ai-memory는 이 한계를 없앱니다.
- 에이전트를 넘나듭니다. Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro 등 20개가 넘는 하네스가 하나의 공유 기억을 씁니다. 작업 도중 Claude Code를 종료하고 같은 폴더에서 Codex를 열면, 어디까지 했고 무엇이 실패했고 무엇이 남았는지 적힌 핸드오프를 다음 에이전트가 받습니다. 핸드오프는 타입이 있는 프로토콜이라 각각 소유자가 있고 정확히 한 번만 가져갈 수 있어요.
- 요약뿐 아니라 세션을 이어 줍니다.
ai-memory run으로 에이전트를 시작하면, Claude Code를 종료하고ai-memory run codex를 실행했을 때 Codex가 공유 워크스트림과 함께 Claude의 보이는 기본 기록을 임시로 투영한 개인용 파일을 받습니다. 원격 서버는 하네스와 세션 식별 정보만 받고 로컬 대화 경로나 내용은 받지 않습니다. 하네스를 직접 실행하면 예전과 똑같이 동작합니다. - 프로젝트를 넘나듭니다. 패키지 매니저, 테스트 구성, 구조 습관 같은 평소 작업 방식의 작은 프로필이 새 저장소의 세션 시작 때마다 전달됩니다. 각 저장소 규칙 파일 아래의 기본값으로 쓰이고, 혼자 쓸 때는 기본으로 켜져 있으며 공유 서버에서는 선택이고 사람마다 비공개입니다.
- 컴퓨터를 넘나듭니다. 기억은 내가 돌리는 서버(같은 노트북, 홈랩, 어디든)에 있어서, 데스크톱에서 두고 온 프로젝트를 노트북에서 같은 지식과 같은 열린 질문으로 이어갈 수 있어요.
- 팀에서도 씁니다. 모두가 한 서버를 바라보면 한 사람의 세션이 배운 것을 모두의 에이전트가 찾아 쓸 수 있습니다. 지식은 프로젝트별로 공유되고 개인 핸드오프는 개인에게 남습니다. 다중 사용자 인증, 사람별 기여 기록, 감사 로그가 유료 기능이 아니라 기본으로 들어 있습니다.
- 기억은 평범한 마크다운입니다. 원본은 일반
.md파일로 된 git 기반 위키입니다.grep으로 찾고, Obsidian으로 열고, 손으로 고치고,rsync로 옮길 수 있어요. 데이터베이스는 파일에서 언제든 다시 만들 수 있는 색인일 뿐이며, 관리할 벡터 저장소도 바이너리에 갇힌 내용도 없습니다. - 작업을 조용히 기록합니다. 라이프사이클 훅이 일어난 일(프롬프트, 도구 호출, 세션 경계)을 기록하고, 저장되기 전에 타입이 있는 개인정보 경계에서 정리하며, 서버가 읽기 쉬운 페이지로 통합합니다. 기억하라고 시킬 필요가 없고, 기본 경로는 LLM 호출이 0회라서 캡처 · 검색 · 핸드오프 모두 API 키 없이 동작합니다.
- LLM 없이도 기억이 나이 듭니다. 기억은 티어별로 조절할 수 있는 일정에 따라 감쇠하고, 자주 쓰는 기억은 더 천천히 감쇠합니다(페이지를 열거나 검색하거나 링크로 도달하면 사용으로 셉니다). 오래된 에피소드 노트는 버리지 않고 파일 경로 · 오류 코드 · 결정 같은 핵심 사실로 압축할 수 있고, 거의 같은 내용은 하나로 합쳐지며, 모순으로 보이는 것은 표시됩니다. 모두 API 호출 없이 이뤄지고, 아무것도 완전히 지우지 않습니다(원본은 git과 버전 체인에 남고
restore-page로 되돌림). 접근 가중 보존은 기억을 더 오래 남기기만 하므로 항상 켜져 있고, 내용을 고치거나 버리는 부분(압축 · 중복 제거 · 티어별 곡선)은 켜기 전까지 꺼져 있습니다. - 원하면 "꿈"도 꿉니다. LLM을 설정하면 선택 기능으로, 한가할 때 백그라운드에서 오래된 노트 묶음을 하나의 일관된 페이지로 다시 쓰고 작업이 돌아오면 바로 멈춥니다. 원본은 지우지 않고(합치기 전 버전은 접근 가능), 기본은 꺼져 있습니다.
- 스스로에 대해 솔직합니다. 자체 완결형 바이너리 하나로 배포됩니다. 삭제 명령은 "삭제"가 정확히 무슨 뜻인지 밝히고, 쓰기 한계(약 700건/초)는 추측이 아니라 측정한 값이며, 모든 변경은 감사 로그에 남습니다.
동작 방식
capture ──▶ consolidate ──▶ recall ──▶ handoff
hooks session-end search next agent,
observe summaries as + brief any harness
silently wiki pages injection
에이전트는 작업 중 라이프사이클 훅으로 정리된 관찰 기록을 보냅니다. 세션이 끝나면 관찰 기록이 프로젝트 위키의 일관된 마크다운 페이지가 됩니다(선택적으로 LLM이 작성하고, 없어도 쓸모 있습니다). 어떤 컴퓨터의 어떤 에이전트든 다음 세션은 크기가 제한된 브리핑을 받고, 전문 검색 · 엔티티 · 링크 · (선택) 벡터를 하나의 순위로 합쳐 모든 것을 검색할 수 있습니다. 에이전트 간 핸드오프는 바통을 명시적으로 넘깁니다.
선택 기능으로 서버가 그리는 관리 콘솔(사용자 관리, 세션 조회 · 삭제, 개인 MCP API 키)이 있습니다. --features management-ui로 빌드하고 serve --transport http --enable-management-ui로 시작해야 하며, 빌드 때와 실행 때 모두 켜야 합니다. 전체 설계는 docs/ARCHITECTURE.md에 있습니다.
지원 현황
아래 항목은 모두 CI가 확인하는 1차 통합(MCP 등록, 라이프사이클 훅, 또는 둘 다)입니다. 에이전트별 주의점이 담긴 전체 표는 docs/support-matrix.md에 있습니다.
| 영역 | 상태 |
|---|---|
| Linux · NixOS 모듈 · macOS · Windows(WSL2) | 지원 |
| 네이티브 Windows | 실험적 |
| Claude Code · Codex · Command Code · Devin CLI · OpenCode(V1/V2 자동 감지) · Cursor · Gemini CLI · Oh My Pi / OMP · Pi · OpenClaw · Antigravity CLI · Grok Build CLI · Zero · ZCode · Kimi Code · Kiro CLI · GitHub Copilot CLI · Factory Droid · Meta Muse Code · IBM Bob · Qwen Code · Qoder · Hermes Agent · GrizzyBot | 지원 |
| Claude Desktop · Swival CLI · VS Code Copilot · Zed · FreeBuff · Prime Agent | MCP 전용 |
| Pool · CodeBuddy Code | 훅 전용 |
| DeepSeek Harness (DSH) · Cline CLI | 훅 + MCP |
| Crush | 관리형 전용 |
| 관리형 워크스트림 | 선택(opt-in) |
| LLM / 인증 제공자 · 임베딩 제공자 | 지원 |
다른 도구에서 오셨나요?
대부분의 에이전트 기억 도구는 한 가지에 집중합니다. 턴마다 원자적 사실 추출, 시간 지식 그래프, 에이전트가 직접 고치는 기억 OS, 호스팅 컨텍스트 API 같은 것들이죠. ai-memory는 git 기반 마크다운 위키를 원본으로 하고 검색용 색인을 따로 둡니다. 라이프사이클 훅으로 자동 캡처하고, 에이전트 · 컴퓨터 · 사람 사이에서 공유하며, 기본은 LLM 호출 0회입니다.
| 쓰던 도구 | 비슷한 점 | 얻는 것 |
|---|---|---|
| Mem0 / 사실 추출기 (LangMem) | 턴마다 자동 캡처 | 기억이 불투명한 사실 행이 아니라 내가 고칠 수 있는 읽기 쉬운 페이지로 정리됨. 클라우드 API 키 없이 전문 검색 + 엔티티 + 그래프(+ 로컬 벡터)를 합쳐 검색 |
| Zep / Graphiti (시간 지식 그래프) | 시간 추론, 타입 있는 관계 | 그래프 DB를 따로 세우지 않고 바이너리 하나로 준(準)양시간 기능(as_of, 버전 필터 검색)과 타입 있는 간선 |
| mcp-memory-service (사실 행, SQLite) | SQLite + 로컬 임베딩, 훅 캡처, 타입 있는 간선, 정직한 수치 | 사람이 고칠 수 있는 마크다운 페이지, 한 번만 가져가는 에이전트 간 핸드오프, 기본은 LLM 없이 되돌릴 수 있게(supersede-not-delete + restore-page) 동작하는 노화 기능(기본 꺼짐) |
| basic-memory (파일 우선 마크다운) | 디스크의 마크다운이 원본 | 자동 라이프사이클 캡처, 그 위의 전문 검색 / 엔티티 / 그래프 색인, 에이전트 간 핸드오프, 다중 사용자 공유가 기본 제공 |
| Claude Code 내장 기억 | "내 프로젝트 기억"의 편리함, 설정 없음 | 컴퓨터와 에이전트 사이 동기화, 검색, 팀 사용, 도구 라이프사이클 캡처(노트북마다 있는 MEMORY.md와 다름) |
| Hindsight / OpenViking (LLM · VLM이 루프 안에 있음) | 백그라운드 통합 루프가 있는 살아 있는 페이지 / 문서 기억 | 기본은 LLM 없이 도는 자체 완결형 바이너리, 거울이 아니라 원본인 마크다운 파일, 한 번만 가져가는 핸드오프. 꿈 · 신념 강도 기능은 선택이고 기본 꺼짐이며 원본을 지우지 않음 |
| Supermemory / LiquidLM (호스팅 기억 API) | 자동 수집이 되는 관리형 두 번째 뇌 | 내가 소유한 git 버전 마크다운, 필수 API 비용 없음, 오프라인 동작, 프로젝트별 팀 공유. ai-memory는 일반 보관함이 아니라 이 저장소를 기억함 |
참고한 것들: Karpathy LLM Wiki(검색이 아니라 컴파일), agentmemory(코딩 에이전트의 훅 캡처), basic-memory(디스크 마크다운이 진실), cognee(파이프라인 조합과 트리플릿 임베딩), Hermes Agent(자기 개선 루프), A-MEM(제텔카스텐식 원자 노트).
빠른 시작
Linux · macOS (명령 두 개, root 불필요)
curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
ai-memory setup
install.sh는 OS와 CPU에 맞는 릴리스를 받아 공개된 SHA-256 체크섬과 맞는지 확인하고(맞지 않으면 설치하지 않음) ~/.local/bin/ai-memory에 연결합니다. 이어서 ai-memory setup이 소유자만 읽을 수 있는 파일에 베어러 토큰이 든 데이터 폴더를 만들고, 사용자 서비스(systemd --user 또는 launchd LaunchAgent)를 시작하며, 찾은 에이전트(또는 --agent로 지정한 것)마다 MCP · 훅 · Agent Skills를 연결합니다. 계획과 각 에이전트를 찾은 위치를 보여 주고 먼저 묻습니다. y로 답하거나 연결할 에이전트 번호를 입력하세요. --plan은 계획만 출력하고, --web은 계획을 브라우저 페이지로 보여 주며 체크한 에이전트에 적용하고, --yes는 질문을 건너뛰며, 다시 실행해도 바뀌는 것은 없습니다. 끝나면 에이전트를 다시 시작하고 "이 프로젝트에 대해 뭘 기억해?"라고 물어 ai-memory로 답하는지 확인해 보세요. 자세한 내용은 docs/install.md, AI 에이전트가 대신 설치할 때는 INSTALL_FOR_AGENTS.md를 따르면 됩니다.
Claude Code와 Codex는 바이너리를 위처럼 설치한 뒤 마켓플레이스 플러그인으로 연결할 수도 있습니다.
claude plugin marketplace add akitaonrails/ai-memory && claude plugin install ai-memory@ai-memory
codex plugin marketplace add akitaonrails/ai-memory && codex plugin add ai-memory@ai-memory
Codex는 /hooks에서 훅을 신뢰할지 묻습니다.
Windows (명령 두 개, 관리자 권한 불필요)
PowerShell에서:
irm https://github.com/akitaonrails/ai-memory/releases/latest/download/install.ps1 | iex
ai-memory setup
install.ps1은 릴리스 zip을 체크섬과 대조하고 %LOCALAPPDATA%\Programs\ai-memory에 풀어 사용자 PATH에 추가합니다. 이어서 ai-memory setup이 Linux · macOS와 같은 일을 하되, 서비스 대신 로그온 항목을 만들어 로그인하면 콘솔 창 없이 서버가 시작되고 실패하면 다시 시작합니다. 다른 Windows 구성(WSL2, Docker Desktop, 진짜 Windows 서비스)은 docs/windows.md에 있습니다. Scoop(3.4.0 이상)도 쓸 수 있습니다.
scoop bucket add akitaonrails https://github.com/akitaonrails/scoop-bucket
scoop install ai-memory
ai-memory setup
Arch Linux (AUR)
/usr/bin/ai-memory, 패키지된 훅 소스, 시스템 · 사용자 systemd 유닛을 설치합니다.
yay -S ai-memory-bin # 미리 빌드한 Linux x86_64/aarch64 바이너리
yay -S ai-memory # 소스에서 빌드
ai-memory setup # 데이터 폴더, 사용자 서비스, 에이전트, 자체 점검
Homebrew (macOS · Linux)
macOS와 Linux(Bazzite나 Fedora Silverblue 같은 불변 배포판 포함)에 미리 빌드한 바이너리와 훅 소스를 설치합니다.
brew install akitaonrails/tap/ai-memory
ai-memory setup # 데이터 폴더, 사용자 서비스, 에이전트, 자체 점검
ai-memory setup과 brew services start ai-memory 중 하나만 쓰세요.
Fedora (RPM)
최신 릴리스에서 x86_64 또는 aarch64 RPM을 받아 설치합니다.
sudo dnf install ./ai-memory-*.rpm
ai-memory setup
시스템 서비스로 설치하면 패키지 유닛으로 /var/lib/ai-memory와 /etc/ai-memory/를 씁니다.
macOS (메뉴 막대 앱)
네이티브 ai-memory 바이너리와 hooks/ 폴더를 담은 독립 .app입니다. LaunchAgent를 시작하고 메뉴 막대에서 /web, ai-memory status, config.toml을 열 수 있습니다. 위키 · SQLite · 설정 · 모델은 ~/Library/Application Support/ai-memory에 있어서 앱을 바꿔도 업데이트만 됩니다. 소스 빌드와 같은 Rust 툴체인과 Xcode / Swift 6이 필요합니다.
git clone https://github.com/akitaonrails/ai-memory
cd ai-memory
./companions/ai-memory-macos/build.sh
open "companions/ai-memory-macos/dist/AI Memory.app"
AI Memory.app을 /Applications로 옮기고 메뉴에서 Install & Start Server를 누르세요(Dock 아이콘 없음). 앱에 포함된 바이너리로 에이전트를 연결합니다.
BIN="/Applications/AI Memory.app/Contents/Resources/runtime/ai-memory"
"$BIN" setup --no-service
미리 빌드한 tarball과 앱 없는 launchd 방법은 docs/macos.md에 있습니다.
Docker
Docker 또는 Podman과 지원 현황 표의 에이전트 CLI(또는 MCP를 쓰는 아무 도구)가 필요합니다. 공개 이미지는 linux/amd64와 linux/arm64를 모두 지원해 Apple Silicon Mac과 ARM64 Linux에서도 에뮬레이션 없이 받을 수 있습니다.
Docker 빠른 시작은 인증이 없습니다. 컨테이너가 init을 실행하지 않아 토큰 없이 시작합니다. 서버는 loopback에만 열려 있어 바깥에서는 접근할 수 없지만 같은 컴퓨터의 프로세스와 브라우저 페이지는 접근할 수 있습니다. ai-memory init을 실행한 네이티브 설치는 기본으로 베어러 토큰이 생깁니다.
# 1. ai-memory CLI 래퍼 설치(홈 폴더를 마운트한 컨테이너에서 바이너리를 실행하는 작은 셸 스크립트).
# 호스트 파일시스템에 둘 것은 이것뿐입니다.
mkdir -p ~/.local/bin
wrapper_tmp="$(mktemp -d)"
trap 'rm -rf "$wrapper_tmp"' EXIT
wrapper_base=https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper
curl -fsSL "$wrapper_base" -o "$wrapper_tmp/ai-memory-wrapper"
curl -fsSL "$wrapper_base.sha256" -o "$wrapper_tmp/ai-memory-wrapper.sha256"
expected="$(awk 'NR == 1 { print $1 }' "$wrapper_tmp/ai-memory-wrapper.sha256")"
if command -v sha256sum >/dev/null 2>&1; then
actual="$(sha256sum "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
else
actual="$(shasum -a 256 "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
fi
[ -n "$expected" ] && [ "$actual" = "$expected" ] || { echo "wrapper checksum mismatch" >&2; exit 1; }
install -m 0755 "$wrapper_tmp/ai-memory-wrapper" ~/.local/bin/ai-memory
rm -rf "$wrapper_tmp"
trap - EXIT
# 2. 서버 시작. LLM / 임베딩 줄을 빼면 LLM 없이 동작합니다(FTS5 검색은 키 없이 됨).
docker run -d --name ai-memory \
--restart unless-stopped \
-p 127.0.0.1:49374:49374 \
-v ai-memory-data:/data \
-e AI_MEMORY_LLM_PROVIDER=anthropic \
-e ANTHROPIC_API_KEY=sk-ant-... \
-e AI_MEMORY_EMBEDDING_PROVIDER=openai \
-e OPENAI_API_KEY=sk-... \
docker.io/akitaonrails/ai-memory:latest
# 3. 에이전트 CLI를 두 명령으로 연결. 래퍼가 마운트와 클라이언트별 설정 경로를 처리합니다.
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply
다른 에이전트는 이름만 바꿔 같은 두 명령을 쓰면 됩니다(--client codex, --agent codex, --agent gemini-cli, --client cursor 등 지원 현황 표의 모든 행). 이제 Claude Code 세션을 평소처럼 시작하면 모든 프롬프트와 도구 호출이 ai-memory에 쌓이고, 다음 세션은 어디까지 했는지 적힌 핸드오프를 보게 됩니다. 업데이트는 ai-memory upgrade(체크섬 확인 후 GitHub 릴리스로 교체 + 훅 새로 고침)를 씁니다. 2.x를 3.0으로 올린다면 먼저 docs/upgrading-to-3.0.md를 읽으세요.
같은 프로젝트에서 에이전트 둘을 동시에 쓰거나 팀원이 한 서버를 써도 바로 동작합니다. "현재 프로젝트" 포인터가 기본으로 호출자별로 분리되기 때문이에요(v1.39 이상). 자세한 내용은 docs/auto-scope.md를 보세요.
헷갈리면 ai-memory run으로 시작하세요
가장 권장하는 실행 방법입니다. 하네스를 처음 실행할 때 훅과 MCP가 없으면 자동으로 설치하고, 알맞은 프로젝트 범위를 맞춰 주며, 공유 기억 위에 하네스 간 세션 연속성을 더합니다. 모두 한 번만 이뤄지고 반복해도 안전합니다. 서버에 닿지 않으면 경고한 뒤 로컬에 캡처를 쌓으며 실행하고, 서버가 돌아오면 ai-memory recover를 실행합니다. --require-server를 붙이면 대신 실패합니다.
ai-memory run claude
ai-memory run codex --yolo # 같은 워크스트림 + 로컬 Claude 기록 자료
ai-memory run --profile work claude # 재사용하는 config.toml 환경 / 계정 프리셋
ai-memory continue # 가장 최근 관리형 체크아웃 이어서
ai-memory resume # 이 체크아웃의 모든 워크스트림에서 고르기
ai-memory resume --search auth # 이름으로 워크스트림 찾기
ai-memory resume --all # 연결된 모든 체크아웃에서 고르기
하네스가 실제로 바뀌면 받는 에이전트는 "이어서 해 줘" 같은 요청에 AI_MEMORY_PREVIOUS_SESSION_HISTORY가 가리키는 임시 마크다운 기록을 먼저 읽습니다(관리형 실행이 끝나면 파일이 사라지고 실행한 컴퓨터에만 있음). 한도 소진처럼 갑자기 끊겨 이전 하네스가 핸드오프를 못 남긴 경우를 위한 것입니다. 자동 연결을 끄려면 --no-autowire 또는 AI_MEMORY_RUN_AUTOWIRE=false를 쓰고, ai-memory uninstall --apply는 설치한 것만 모두 제거합니다. 설치 명령은 반복해도 안전하며 건드리는 파일 옆에 시각이 붙은 백업을 남깁니다.
NixOS
플레이크가 nixosModules.default(전용 ai-memory 시스템 사용자 + 강화된 systemd 샌드박스가 있는 systemd.services.ai-memory 유닛)를 제공합니다. 모듈을 가져오지 않으면 nix build, nix run, nix develop, CLI는 그대로입니다. AI_MEMORY_AUTH_TOKEN 같은 비밀은 settings에 넣지 말고 ageSecret, sopsSecret, environmentFile 중 하나로 넘기세요. 모든 옵션은 nix/nixos-module.nix에 있습니다.
{
inputs.ai-memory.url = "github:akitaonrails/ai-memory";
outputs = { nixpkgs, ai-memory, ... }: {
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
ai-memory.nixosModules.default
{
services.ai-memory = {
enable = true;
settings = {
allowed_hosts = [ "localhost" "127.0.0.1" "::1" "homelab.example" ];
log_level = "info";
};
};
}
];
};
};
}
평소 사용
평소에는 ai-memory를 거의 의식하지 않습니다. 훅이 프롬프트 · 도구 호출 · 세션 경계를 기록하고, 세션이 끝나면 읽기 쉬운 위키 페이지가 되며, 다음 세션은 핸드오프로 시작합니다.
- "어디까지 했지?"라고 물으면 대기 중인 핸드오프에서 이어갑니다.
- 로컬 PDF · DOCX · PPTX · XLSX · 마크다운 · VTT/SRT 대본을
ai-memory-importer의document명령으로 기여자가 표시된 정리된 기억으로 가져올 수 있어요. - "X에 대해 얘기한 적 있어?", "Y를 기억에서 찾아 줘"로 위키를 검색합니다.
- 큰 위키는
memory_query필터(path_prefix,tag,kind,tier)로 순위 전에 좁힙니다. - "최근 상황 알려 줘"로 프로젝트 요약을,
ai-memory recent(--global이면 모든 프로젝트)로 가장 새 페이지 목록을 봅니다. - 띄어쓰기 없는 한국어 · 중국어 · 일본어 검색도 됩니다. LLM 없는 검색이 띄어쓰기 없는 한자 · 가나 · 한글 부분 문자열을 찾아 줍니다.
- 몇 달치 기록이 있는 기존 프로젝트를 들일 때는
ai-memory bootstrap을 한 번 실행합니다. --enable-web으로 서버를 시작하면 위키를 읽기 전용으로 보는 브라우저 화면,/web/graph링크 그래프,/web/workstreams관리형 워크스트림 개요,/api/v1JSON API가 열립니다. 베어러 토큰만 있고 사용자 계정이 없는 서버(새 설치 모두)에서는 아무 사용자 이름과<data_dir>/auth-tokens/default파일 내용을 비밀번호로 씁니다.- 프로젝트 대시보드에서 Claude Code와 Codex의 응답 토큰 사용량을 조사하고 밝음 · 어두움 · 시스템 테마를 고릅니다. 프로젝트에서 에이전트, 세션, 개별 응답까지 내려가 볼 수 있고, 운영자는 웹 에이전트 받은편지함으로 등록된 에이전트에 요청을 쌓을 수 있습니다.
- 호스트의 하네스 설정을
ai-memory backup-agents -o agent-assets.tar.gz로 백업하고,ai-memory restore-agents -i agent-assets.tar.gz로 복원을 먼저 검사한 뒤 내용을 확인하고서야--apply를 붙입니다.
검색 모드, 엔티티, 피드백, 브리핑, 웹 API는 docs/usage.md와 docs/use-cases.md에 있습니다. 화면 언어는 ai-memory --language pt-BR status 또는 AI_MEMORY_LANGUAGE=pt-BR로 바꿀 수 있고, 웹 화면은 브라우저 언어를 따릅니다.
팀과 여러 컴퓨터
서버를 홈랩이나 LAN 호스트처럼 닿을 수 있는 곳에서 돌리고 모든 컴퓨터와 팀원이 그곳을 바라보게 하세요. 지식은 프로젝트별로 공유되고, 개인 핸드오프는 개인에게 남으며, 모든 쓰기에는 기여자가 표시되고 감사 기록이 남습니다. 다중 사용자 인증(비밀번호, API 자격 증명)이 기본 제공됩니다. 계정과 소유권은 docs/users.md, 서버 구성은 docs/deploy.md에서 시작합니다. 반드시 지킬 규칙은 하나입니다. 데이터 폴더 하나에 서버 하나만, 둘은 안 됩니다.
둘 다 기본 꺼짐인 선택 기능이 있습니다. serve --enable-session-management는 로그인한 사용자가 자기 세션을 조회하고 삭제하게 하고, serve --enable-self-service-keys는 자기 aim_ API 키를 발급 · 폐기하게 합니다.
보안
서버는 기본으로 loopback에만 열립니다. 새 ai-memory init은 루트 베어러 토큰을 데이터 폴더에 만들고 훅 · CLI · ai-memory mcp-bridge stdio 브리지가 거기서 읽으며, 하네스 설정에는 절대 쓰지 않습니다. 이후 단계는 점진적입니다. LAN용 베어러 토큰, 사용자별 계정, 훅용 OIDC 기기 인증, 리버스 프록시의 TLS 순입니다. 캡처는 저장 전에 타입 있는 개인정보 경계에서 정리되고, 저장소별 [capture] 규칙으로 경로를 제외하거나 허용 목록 모드로 뒤집을 수 있습니다. loopback 밖의 사람 로그인은 기본으로 HTTPS가 필요합니다.
전체 모델은 docs/security.md, docs/users.md, docs/https-via-proxy.md에 있고, 데이터 흐름은 DATA_HANDLING.md를 보세요.
LLM 제공자
선택 사항입니다. 모든 것이 LLM 호출 없이 동작하고, 제공자를 더하면 세션 요약이 좋아지고 의미 검색이 켜집니다. 통합에는 Anthropic, OpenAI(OAuth 포함), Codex CLI 자격 증명 재사용, GitHub Copilot, Gemini, OpenCode(Go · Zen), Cursor Agent CLI, 모든 OpenAI 호환 엔드포인트(Ollama, LM Studio, vLLM)를 쓸 수 있고, 임베딩에는 OpenAI, Voyage, Gemini, 키 없는 OpenAI 호환 엔드포인트를 쓸 수 있습니다. 설정은 docs/llm-providers.md에 있습니다.
아키텍처
Rust 바이너리 하나가 MCP/HTTP 서버를 돌리며 데이터 폴더 하나를 소유합니다.
<data_dir>/
├── wiki/ # 마크다운 원본, git 버전 관리
├── raw/ # 정리된 관리형 워크스트림 대화 조각(수정 불가)
├── db/ # FTS5, 엔티티, 임베딩을 포함한 SQLite 색인
├── models/ # 로컬 임베딩 모델용 예약
└── logs/ # 롤링 트레이싱 출력
훅이 관찰 기록을 서버에 POST하면, 서버는 쓰기를 SQLite 쓰기 단일 통로로 직렬화하고 세션 관찰 기록을 마크다운 페이지로 컴파일하며, FTS5 · 엔티티 일치 · 그래프 이웃 RRF · (선택) 벡터 RRF · 캡처된 턴이 맞을 때 세션 페이지를 끌어올리는 관찰 근거 스트림 · 제한된 출처 권위 조정으로 검색을 제공합니다. 데이터 흐름 도식, 크레이트 구성, 스키마, 불변식은 docs/ARCHITECTURE.md에 있습니다.
문서
사용자용
| 파일 | 내용 |
|---|---|
| docs/cookbook.md | "X를 하고 싶다" 식 요령집. 이전 작업 불러오기, 프로젝트 규칙 남기기, 기존 지식 가져오기, 에이전트 둘 · 저장소 둘 협업. 여기서 시작하세요 |
| docs/install.md | 설치 요리책. 모든 에이전트 CLI, 모든 대안(curl, 소스 빌드, Docker 없이, 인증 없이), 다른 컴퓨터의 서버 연결 |
| docs/usage.md | 핸드오프, 능동 기억 질의, 라우팅 스니펫과 Agent Skills, 웹 UI, 위키 원본 보기 |
| docs/cross-project-profile.md | 프로젝트를 넘는 프로필: 모든 프로젝트에 기본값으로 전달되는 내 평소 선택 |
| docs/managed-workstreams.md | ai-memory run으로 하네스를 넘나드는 연속성 |
| docs/agent-messaging.md | 프로젝트 간 에이전트 메시지(한 번만 가져가는 받은편지함) |
| docs/marker-file.md | .ai-memory.toml로 워크스페이스 / 프로젝트 라우팅(모노레포, 워크트리, 업무 / 개인 분리) |
| docs/macos.md · docs/windows.md | macOS · Windows 설치 방법 |
| docs/mcp-install.md | 클라이언트별 MCP · 라이프사이클 안내 |
| docs/programmatic-memory.md | 어떤 도구에서든 ai-memory 쓰기: MCP 쓰기 · 질의 · 핸드오프 호출 |
| docs/users.md · docs/deploy.md · docs/https-via-proxy.md | 다중 사용자 · 서버 배포 · 리버스 프록시 TLS |
| docs/lifecycle-ops.md · docs/backup.md | 삭제 · 이름 변경 · 병합 · 백업 · 복원 · 초기화 · 재색인 전에 읽을 것, 원격 git 백업 |
| docs/benchmarks/ | 근거와 함께 공개한 검색 품질 수치(저장소 안 도구로 재현 가능) |
기여자용
| 파일 | 내용 |
|---|---|
| docs/ARCHITECTURE.md | 데이터 흐름, 크레이트 구성, 불변식, 스키마 |
| docs/design-decisions.md | v1 전체 설계 |
| docs/companion-crates.md | 선택 동반 프로젝트: importer, 외부 라이프사이클 릴레이, 팀 위키 동기화, TypeScript SDK, 데스크톱 설치 프로그램(서명 없는 미리 보기) |
커뮤니티 글
사용자가 쓴 글로, 이 저장소에서 관리하지 않으니 쓰는 버전과 맞는지 확인하세요.
- Linux에 ai-memory 설치 · 설정 (포르투갈어, LinuxPro, v2.6.3 기준)
- ai-memory v2.4에서 v2.6.3까지 (포르투갈어, LinuxPro)
내장 웹 UI에는 /web/docs의 문서와 /web/docs/changelog의 변경 기록도 있습니다. 기능별 준비물과 확인 방법은 기능 활성화 안내를 보세요.
라이선스
MIT. LICENSE를 보세요.