자체 설치판: 설치한 뒤 처음 할 일

AiAkiv 무료 자체 설치판(사용자 5명까지)을 설치한 뒤 읽는 안내입니다. 기억을 저장하고 찾는 법, AI 에게 말로 관리를 부탁하는 법, 사용자와 팀과 키를 더하는 법, 다른 컴퓨터의 팀원을 연결하는 법, 내보내기와 가져오기, 백업과 새 버전, 엔진이 밖으로 보내는 것, 막혔을 때 볼 것을 한곳에 모았습니다.

한 줄 요약. 설치가 끝났으면 AI 프로그램을 다시 시작하고 "ak save" 로 저장해 보세요. 사용자 추가, 내보내기 같은 관리는 관리 스킬을 설치한 AI 에게 말로 부탁하면 됩니다. 직접 하고 싶으면 설치 폴더에서 aiakiv-admin 명령을 씁니다.

이 문서는 AiAkiv 무료 자체 설치판(직접 설치하는 무료판, 활성 사용자 5명까지)을 설치 프롬프트로 설치한 다음에 읽는 안내입니다. 아직 설치하지 않았다면 https://app.aiakiv.com/selfhost 에서 로그인한 뒤 설치 프롬프트를 받으세요.

설치가 끝나면 생기는 것

엔진: Docker 컨테이너 두 개(엔진과 데이터베이스)가 이 컴퓨터에서 돕니다. 주소는 http://127.0.0.1:7777/mcp 이고(설치 때 다른 포트를 골랐으면 그 번호), 이 컴퓨터 안에서만 열립니다. 컴퓨터를 다시 켜도 Docker 가 켜지면 엔진도 다시 뜹니다.
설치 폴더: 보통 ~/.aiakiv/engine(Windows 는 $HOME\.aiakiv\engine)입니다. 안에 이런 것이 있습니다.
- aiakiv-compose.yml 과 .env: 엔진 설정입니다. .env 에는 데이터베이스 비밀번호가 들어 있으니 남에게 보내지 마세요.
- secrets/: 설치 때 만든 키 파일입니다. 사람마다 자기 키를 전한 뒤 지우세요.
- bundle-<버전>/: 안내 문서(README.md, PREPARE.md, aiakiv-admin.md), 백업과 새 버전용 프롬프트(prompts/), 스킬(skills/)이 있습니다.
AI 프로그램 연결: 설치 때 고른 프로그램에 AiAkiv-Local 이라는 MCP 서버와 스킬이 들어가 있습니다. 새 서버와 스킬은 그 프로그램을 다시 시작해야 보입니다.
기억은 이 컴퓨터에만 있습니다. AiAkiv 클라우드와 이어져 있지 않습니다. 그래서 백업이 중요합니다(아래 "백업과 새 버전").

AiAkiv 클라우드에 있는 웹 콘솔, 로그인, 카드, 팀 간 링크, 공개 기억, 앱은 무료 자체 설치판에 없습니다. 관리는 모두 명령으로 합니다.

기억 저장하고 찾기

쓰는 방법은 클라우드와 같습니다.

저장: 대화 중에 "ak save" 라고 하면 AI 가 지금까지의 내용을 정리해 저장합니다. "이것 기억해 줘" 만으로는 저장하지 않습니다.
찾기: 평소처럼 물으면 AI 가 필요할 때 기억을 찾아 씁니다. 꼭 찾게 하려면 "AiAkiv-Local 에서 ○○ 를 찾아 줘" 라고 하세요.
연결 확인: 처음에는 "AiAkiv-Local 에서 install check 를 검색해 줘" 라고 해 보세요. 설치 때 남긴 시험 기억이 나오면 연결된 것입니다.
어느 기억에 저장되나: 키가 정합니다. 키는 사람 한 명과 기억 하나(개인 기억 또는 공유 팀)에 묶여 있습니다. 팀이 여럿이면 팀마다 키가 다르고, 폴더마다 다른 팀을 쓰려면 그 폴더에 설정 파일을 둡니다(설치 프롬프트 9단계에서 "한 폴더만" 을 고른 경우). 폴더 설정 파일에는 키가 들어 있으니 git 에 올리지 마세요.

저장과 검색을 잘 쓰는 요령은 저장하기와 찾기에 있습니다. 클라우드 기준 문서지만 요령은 같습니다.

가장 쉬운 방법: AI 에게 말로 부탁하기

설치 때 관리 스킬 aiakiv-local-admin 을 설치했다면, 엔진을 설치한 컴퓨터의 AI 에게 말로 부탁하면 됩니다. AI 가 알맞은 명령을 고르고, 지우거나 바꾸는 일은 먼저 계획을 보여 주고 묻습니다.

하고 싶은 일	이렇게 말하세요
상태 보기	"AiAkiv 엔진 상태 알려 줘"
사람 더하기	"AiAkiv 에 민수를 사용자로 추가하고 개발팀에 넣어 줘"
팀 만들기	"AiAkiv 에 기획팀을 만들어 줘. 소유자는 나야"
키 다시 받기	"민수가 키를 잃어버렸어. 다시 발급해 줘"
내보내기	"AiAkiv 개발팀 기억을 파일로 내보내 줘"
가져오기	"이 파일을 AiAkiv 개발팀으로 가져와 줘"
새 버전 확인	"AiAkiv 새 버전 나왔어?"

관리 스킬을 설치하지 않았다면 설치 폴더의 bundle-<버전>/skills/aiakiv-local-admin/ 폴더를 AI 프로그램의 스킬 폴더(Claude Code 는 ~/.claude/skills/, Codex 와 Gemini CLI 는 ~/.agents/skills/)에 복사하고 프로그램을 다시 시작하세요.

관리 명령 직접 쓰기

명령은 엔진 컨테이너 안에서 돕니다. 설치 폴더에서 이렇게 부릅니다.

docker compose -f aiakiv-compose.yml exec engine aiakiv-admin status

아래에서는 앞부분을 줄여 aiakiv-admin <명령> 으로 적습니다. 실제로는 늘 앞에 docker compose -f aiakiv-compose.yml exec engine 을 붙입니다. Windows 의 PowerShell 에서도 같은 명령입니다.

aiakiv-admin status: 사용자 수와 한도, 팀, 기억 수, 데이터베이스 크기, 새 버전 정보를 봅니다.
aiakiv-admin dashboard: 한 화면 요약입니다.
지우거나 바꾸는 명령은 --yes 없이 돌리면 계획만 보여 주고 아무것도 바꾸지 않습니다. 계획을 확인한 뒤 같은 명령에 --yes 를 붙여 다시 돌리세요.
인자가 궁금하면 --help 를 붙이세요. 명령 하나하나의 설명은 설치 폴더의 bundle-<버전>/aiakiv-admin.md 에 있습니다.
키는 발급할 때 딱 한 번 나옵니다. 키를 만드는 명령(user add, team create, team add, key issue, key reissue)의 결과는 화면 대신 파일에 받아 두세요. 예: ... aiakiv-admin user add 민수 --json > secrets/민수-personal.json. PowerShell 은 > 파일 대신 | Out-File -Encoding utf8 파일 을 씁니다.

사용자 더하기

활성 사용자는 5명까지입니다. 여섯째 사용자는 거절됩니다.

사람을 더하는 일도 AI 에게 "AiAkiv 에 민수를 사용자로 추가하고 개발팀에 넣어 줘" 라고 시키면 됩니다. AI 가 키를 화면에 내지 않고 secrets/ 폴더의 파일로 받아 둡니다. 직접 하려면 아래 순서대로 합니다.

사용자 만들기: aiakiv-admin user add <이름>. 사용자와 그 사람의 개인 기억, 개인 기억의 키가 생깁니다. 이름은 어느 언어든 되고 64자까지입니다.
팀에 넣기: aiakiv-admin team add <팀> <이름>. 그 팀의 키가 새로 나옵니다. 무료 자체 설치판에서는 팀원 모두가 팀의 기억을 모두 읽고 씁니다.
키 전하기: 키는 사람마다 따로, 가능하면 평문 메일이 아닌 방법으로 전하세요. 전한 뒤 secrets/ 의 그 사람 파일은 지우세요.
그 사람의 AI 프로그램 연결: 서버 이름 AiAkiv-Local, 주소 http://<엔진 컴퓨터 주소>:7777/mcp, 머리글 Authorization: Bearer <키> 로 MCP 서버를 더합니다. Claude Code 라면:
```
claude mcp add --transport http --scope user AiAkiv-Local http://127.0.0.1:7777/mcp --header "Authorization: Bearer <키>"
```
Codex, Cursor, Gemini CLI 의 설정 모양은 설치 프롬프트 9단계에 있습니다. 스킬 aiakiv-local-save-and-recall 과 aiakiv-local-graph-query 도 같이 복사해 주면 그 사람의 AI 가 저장과 검색을 더 잘합니다.

사람 빼기: aiakiv-admin user remove <이름> --yes. 그 사람의 키가 모두 막히고 사용자를 한 명 더 넣을 수 있게 됩니다. 그 사람이 저장한 기억은 남습니다.
팀에서만 빼기: aiakiv-admin team remove <팀> <이름> --yes(소유자는 뺄 수 없습니다).

다른 컴퓨터의 팀원이 쓰려면

엔진은 처음에 이 컴퓨터 안(127.0.0.1)에서만 열립니다. 팀원이 자기 컴퓨터에서 쓰려면 설치한 사람이 엔진을 사내망에 열어야 합니다.

엔진 컴퓨터의 사내망 주소(예: 192.168.0.10)를 확인합니다.
설치 폴더의 .env 에서 AIAKIV_BIND=127.0.0.1 을 그 주소로 바꾸고, docker compose -f aiakiv-compose.yml up -d 로 다시 띄웁니다.
방화벽에서 그 포트(기본 7777) 하나를 사내망에만 허용합니다.
팀원은 주소를 http://192.168.0.10:7777/mcp 처럼 바꿔 연결합니다.

이 연결은 암호화되지 않습니다. 믿을 수 있는 사내망이나 VPN 안에서만 여세요. 공인 인터넷 주소에는 열지 마세요.

팀과 키

공유 팀 만들기: aiakiv-admin team create <팀> --owner <이름>. 팀과 소유자의 키가 생깁니다.
목록: aiakiv-admin team list, aiakiv-admin user list, aiakiv-admin key list(키 값은 나오지 않고 키 id 만 나옵니다).
키를 잃었을 때: aiakiv-admin key reissue <키 id> --yes. 옛 키는 막히고 새 키가 나옵니다. 그 키를 쓰던 AI 프로그램 설정을 새 키로 바꾸고 프로그램을 다시 시작하세요.
컴퓨터를 하나 더 쓸 때: aiakiv-admin key issue <이름> --team <팀> 으로 키를 하나 더 받습니다.
키 막기: aiakiv-admin key revoke <키 id> --yes.
팀 지우기: aiakiv-admin team delete <팀> --yes 는 팀과 기억을 바로 지웁니다. 되돌릴 수 없으니 먼저 내보내기를 해 두세요.
개인 기억은 명령에서 personal:<이름> 으로 부릅니다(예: personal:민수).

내보내기와 가져오기

내보내기 파일(.mweft.tar.gz)은 AiAkiv 클라우드, 무료 자체 설치판, 유료 기업판이 같은 형식을 씁니다. 파일에는 작성자와 권한이 들어가지 않습니다. 받는 쪽에서는 가져오는 사람의 기억으로 들어갑니다.

AI 에게 시키는 것이 가장 쉽습니다. 관리 스킬을 설치한 AI 에게 "AiAkiv 개발팀 기억을 파일로 내보내 줘", "다운로드 폴더의 이 파일을 AiAkiv 개발팀으로 가져와 줘" 라고 하면 파일을 컨테이너에 넣고 꺼내는 일, 가져올 계획 확인, 실제로 넣기까지 AI 가 차례로 합니다. 넣기 전에 몇 건이 들어가는지 보여 주고 묻습니다. 직접 하려면 아래 명령을 씁니다.

명령은 컨테이너 안의 경로를 쓰므로, 파일을 컨테이너 밖으로 꺼내거나 안으로 넣는 일이 한 번 더 있습니다. 아래 DC 는 docker compose -f aiakiv-compose.yml 입니다.

내보내기

DC exec engine aiakiv-admin export 개발팀 --to /data/exports/dev.mweft.tar.gz
DC cp engine:/data/exports/dev.mweft.tar.gz ./dev.mweft.tar.gz

가져오기

DC exec engine mkdir -p /data/imports
DC cp ./dev.mweft.tar.gz engine:/data/imports/dev.mweft.tar.gz
DC exec engine aiakiv-admin import /data/imports/dev.mweft.tar.gz --team 개발팀 --dry-run
DC exec engine aiakiv-admin import /data/imports/dev.mweft.tar.gz --team 개발팀 --yes

--dry-run 은 몇 건이 들어가는지 계획만 보여 줍니다. 확인한 뒤 --yes 로 실제로 넣습니다.
같은 파일을 같은 팀에 두 번 넣어도 두 번째는 모두 건너뜁니다. 같은 파일을 다른 팀에 넣을 수는 없습니다.
중간에 끊기면 같은 명령에 --resume 을 붙여 이어서 합니다.

AiAkiv 클라우드의 기억을 가져올 때

https://app.aiakiv.com 웹 콘솔의 Export / Import 화면에서 팀을 내보내고 파일을 내려받습니다. 팀 소유자만 할 수 있습니다.
위 "가져오기" 대로 넣습니다.

클라우드에서 내보낸 파일에는 검색에 쓰는 벡터가 없어서, 엔진이 가져오면서 벡터를 다시 계산합니다. 시간이 걸립니다. 저희 시험 PC(12코어 CPU)에서 기억 1,000건에 약 8분 반이 걸렸고, 그동안 엔진의 메모리가 3.7GB 까지 올라갔습니다. 팀의 파트 구조, 작성자, 숨긴 기억은 들어오지 않으며 가져오기 계획이 그 사실을 알려 줍니다.

거꾸로 자체 설치판의 기억을 클라우드로 옮길 때는 위 "내보내기" 로 만든 파일을 웹 콘솔의 Export / Import 화면에서 가져옵니다.

백업과 새 버전

기억은 이 컴퓨터에만 있습니다. 디스크가 고장 나면 모두 잃으니, 설치가 끝나면 먼저 백업을 준비하세요. 백업과 새 버전 설치는 설치 폴더의 프롬프트를 AI 에게 붙여 넣어 합니다.

백업, 매일 백업, 되살리기, 다른 컴퓨터로 옮기기: bundle-<버전>/prompts/backup-restore.ko.md
새 버전 설치: bundle-<버전>/prompts/upgrade.ko.md. 먼저 백업하고, 실패하면 이전 버전으로 돌아갑니다. 새 버전 파일은 https://app.aiakiv.com/selfhost 에서 로그인한 뒤 받습니다.

파일을 열어 "여기부터 복사" 줄 아래를 AI 대화창에 붙여 넣으세요. 새 버전이 나왔는지는 aiakiv-admin status 의 새 버전 정보나 "AiAkiv 새 버전 나왔어?" 로 알 수 있습니다.

엔진이 밖으로 보내는 것

엔진은 하루 한 번 AiAkiv 서버(https://app.aiakiv.com)에 요청 두 개를 보냅니다. 보내는 것은 아래가 전부입니다.

새 버전 확인: https://app.aiakiv.com/selfhost/latest.json 을 읽는 요청 하나입니다. 요청에 담아 보내는 값은 없습니다.
사용 보고: https://app.aiakiv.com/selfhost/api/usage 로 아래 다섯 값을 보냅니다.

값	내용	예
`install_id`	이 설치에서 처음 한 번 무작위로 만든 번호	무작위 UUID
`version`	엔진 버전	`0.1.0`
`edition`	제품 종류	`free`
`arch`	CPU 종류	`amd64` 또는 `arm64`
`active_users`	활성 사용자 수	`3`

실제로 보내는 값은 aiakiv-admin status 결과의 usage_report 칸에서 그대로 볼 수 있습니다.

둘 다 끄려면 .env 에 AIAKIV_UPDATE_CHECK=off 줄을 더하고 docker compose -f aiakiv-compose.yml up -d 로 다시 띄우세요. 끄면 엔진은 밖으로 아무 요청도 보내지 않습니다. 인터넷이 없는 컴퓨터라면 이렇게 둡니다. 꺼도 엔진은 똑같이 동작합니다.

막혔을 때

AI 가 AiAkiv-Local 을 못 찾음: AI 프로그램을 다시 시작했는지 보세요. Claude Code 는 claude mcp list 에서 AiAkiv-Local 이 연결됨으로 나와야 합니다.
엔진이 답하지 않음: Docker(Docker Desktop)가 켜져 있는지 보고, 브라우저로 http://127.0.0.1:7777/health 를 열어 "status":"ok" 가 나오는지 보세요. 안 나오면 설치 폴더에서 docker compose -f aiakiv-compose.yml up -d 로 다시 띄웁니다.
키가 거절됨(401): 키가 막혔거나 잘못 들어갔습니다. aiakiv-admin key list 로 키 상태를 보고, 필요하면 key reissue 로 다시 받으세요.
여섯째 사용자가 거절됨: 활성 사용자 5명이 다 찼습니다. 쓰지 않는 사람을 user remove 로 빼면 새 사용자를 넣을 수 있습니다.
그래도 안 되면 docker compose -f aiakiv-compose.yml logs --tail 100 engine 의 내용을 AI 에게 보여 주고 원인을 물어보세요.