MCP로 Codex를 암호화 지식 베이스에 연결하기

Knowtarium은 사람과 각자의 AI 에이전트가 함께 일하는 종단간 암호화 지식 베이스예요. OpenAI의 Codex는 내 컴퓨터에서 실행되며 그곳에서 노트를 복호화하는 작은 서버를 통해 MCP로 연결돼요. 연결되면 Codex는 다음을 할 수 있어요.

• 노트를 검색하고 읽어요. 내가 허락한 워크스페이스와 폴더 안에서 노트 사이의 링크를 따라가고 관련 노트를 찾아요.
• 노트를 만들고 편집해요. 각 변경은 즉시 저장되고, Codex 자신의 키로 서명되며, 기록에 남아요. 그래서 무엇을 했는지 보고 클릭 한 번으로 되돌릴 수 있어요.
• 폴더 지침을 따라요. 앱에서 워크스페이스나 폴더에 쓴 지침(그 AGENTS.md)은 Codex가 그곳에서 읽고 쓸 때마다 전달돼요. Codex는 이 지침에 대해 변경을 제안만 할 수 있고, 직접 바꿀 수는 없어요.
• 원하는 곳에서는 나를 기다려요. 워크스페이스나 폴더에 검토("Ask me first")를 켜면, 그곳에서 Codex의 노트 변경은 내가 승인하거나 거절할 diff로 대기해요. 그곳에서 폴더 변경은 대신 거부되고, Codex가 무엇을 바꾸려 했는지 알려 줘요.
• 노트를 이동하거나 삭제하고 폴더를 바꿔요. 단, 그 권한을 준 경우에만 가능하고, 대화에서 내가 요청할 때만 하도록 안내받아요.

허락하지 않은 워크스페이스나 폴더에 접근하거나, 내 이름으로 서명하거나, 노트를 내가 확인한 것으로 표시하거나, 검토를 켠 곳에서 검토를 건너뛸 수는 없어요. 전체 목록은 에이전트 페이지에 있어요.

Node.js 20 이상(22 또는 24 권장)과 무료 Knowtarium 계정이 필요해요. 터미널을 열고 홈 폴더에서 명령을 실행하세요. npx는 실행되는 폴더를 신뢰하므로, 프로젝트 안에서 실행하면 그 프로젝트의 파일이 Knowtarium의 파일을 대신할 수 있어요.

$ cd ~                          # 프로젝트가 아닌 홈 폴더$ npx knowtarium connect
Opening the browser to connect this computer to Knowtarium.
Connected to workspace ws_8f2k (read and write).
Add Knowtarium to which agents? Codex
added to Codex (/Users/you/.codex/config.toml)
  previous file saved as /Users/you/.codex/config.toml.knowtarium-backup-<time>

1. 이 컴퓨터를 승인하세요. 브라우저에서 Knowtarium이 열려요. 에이전트 이름을 정하고, 접근할 수 있는 범위를 고른 뒤(아래 참고) Allow를 클릭하세요. 단, 직접 명령을 실행한 경우에만요. 브라우저가 터미널에 닿을 수 없는 SSH 환경에서는 대신 양쪽에 표시되는 일치하는 코드를 확인해요.
2. 에이전트를 고르세요. CLI가 컴퓨터에서 찾은 에이전트를 모두 체크된 상태로 보여 줘요. Enter를 누르면 전부에 Knowtarium을 추가하고, 먼저 일부를 해제할 수도 있어요(화살표로 이동, 스페이스로 선택·해제, a로 전체 선택·해제, Esc는 아무것도 추가하지 않음). Codex는 ~/.codex 폴더로 찾아내요.
3. Codex에 항목이 추가돼요. CLI는 Codex의 사용자 설정인 ~/.codex/config.toml(설정했다면 $CODEX_HOME 안)에 Knowtarium을 추가하므로, 모든 프로젝트에서 쓸 수 있어요. 먼저 파일을 파싱하고 Knowtarium 자체의 테이블만 바꾸며, 다른 서버와 설정, 주석은 그대로 두고, 이전 파일은 그 옆에 백업해요. 이 항목은 Codex가 열어 둔 프로젝트가 아니라 항상 홈 폴더에서 서버를 시작해요.
4. 새 서버를 불러오도록 Codex를 다시 시작하세요. 이미 실행 중이던 세션은 종료하고 Codex를 다시 시작하세요.

Codex의 설정에는 비밀번호, 토큰, 키가 들어가지 않아요. 연결은 암호화되어 저장되고, 그 키는 시스템 키체인(키체인이 없으면 나만 읽을 수 있는 파일)에 보관돼요. CLI가 무엇이든 쓰기 전에 무엇을 바꿀지 보려면 npx knowtarium agents --dry-run을 실행하세요. CLI는 오픈 소스이고, 코드는 GitHub에 있어요.

(새 탭에서 원래 크기로 열림) (새 탭에서 원래 크기로 열림)

Knowtarium 플러그인에는 테스트된 knowtarium 릴리스에 고정된 같은 MCP 서버와, Knowtarium 워크스페이스에서 일하기 위한 스킬(knowtarium-conventions)이 들어 있어요. 플러그인도 Node.js 20 이상이 필요하고, 런처는 홈 폴더에서 서버를 시작해요. 터미널에서:

$ codex plugin marketplace add Knowtarium/knowtarium-plugins$ codex plugin add knowtarium@knowtarium

또는 마켓플레이스를 추가한 뒤 Codex에서 /plugins를 입력해 플러그인 브라우저를 열고 knowtarium 마켓플레이스에서 Knowtarium을 설치하세요. OpenAI의 공개 플러그인 디렉터리에는 없으므로 먼저 마켓플레이스를 추가해야 해요.

그런 다음 이 컴퓨터를 한 번 연결하세요. Codex에게 Knowtarium을 연결해 달라고 하면 브라우저가 열려 이 컴퓨터를 승인할 수 있어요. 또는 홈 폴더에서 --no-agents와 함께 명령을 실행하세요. 플러그인이 이미 서버를 실행하므로, 이 플래그를 쓰면 Codex의 설정을 건드리지 않아요.

$ cd ~$ npx knowtarium connect --no-agents

플러그인과 연결 명령, 무엇을 쓸까요?

어느 쪽이든 Codex는 같은 도구와 같은 규칙을 받아요. 하나만 고르세요. Codex에 이미 플러그인이 있으면 명령은 Codex를 체크 해제된 상태로 두어, 명령의 항목이 플러그인의 서버를 대체하지 않게 해요.

명령이 여는 페이지에서 이 연결이 할 수 있는 일이 정해져요. 모든 것은 이 에이전트 하나에만 적용되고, 서버가 이를 강제해요.

• 워크스페이스 하나. 각 연결은 정확히 하나의 워크스페이스에 접근해요. Codex에 다른 워크스페이스를 주려면 npx knowtarium connect를 다시 실행하고, 다른 워크스페이스를 고른 뒤 Codex를 다시 시작하세요. 첫 번째 연결은 그대로 남아요.
• 원하면 일부 폴더만. 필요한 폴더만 체크하세요. 그 위에 있는 폴더의 지침도 읽지만, 그 지침에 대한 변경은 제안할 수 없어요.
• 읽기 또는 읽기·쓰기. 노트에서 답만 얻고 싶다면 읽기 전용으로 시작하세요.
• 편집 이상의 일은 체크할 때만. 노트 이동, 노트 삭제, 폴더 만들기, 이름 바꾸기, 이동, 삭제는 여섯 가지 별도 권한이고, 모두 기본값은 꺼짐이에요.

나중에 앱의 Settings, Agents에서 모두 바꿀 수 있으며, 바꿀 때마다 새 권한 세트에 서명해요. 그곳에서 Codex의 접근을 취소하면 즉시 차단되고 워크스페이스는 새 키를 받으므로, 그 이후에 쓰인 것은 읽을 수 없어요. 터미널에서는 npx knowtarium disconnect가 이 컴퓨터의 접근 권한을 해지하고 로컬 키와 캐시를 삭제해요.

Codex는 상시 지침을 AGENTS.md 파일에서 가져와요. 모든 프로젝트에 적용되는 ~/.codex의 파일 하나, 그리고 git 루트와 Codex를 시작한 위치 사이의 폴더에 있는 파일들이에요(Codex 문서). 이 파일들은 저장소에서 어떻게 일할지 담기에 좋아요. 하지만 결정, 리서치, 회의 메모, 여러 에이전트와 사람이 의지하는 사실 같은 지식 자체를 담기에는 적합하지 않아요.

그게 지식 베이스가 있는 이유예요. 코딩 규칙은 Codex의 AGENTS.md에 두고, Codex가 알게 된 것은 Knowtarium에서 찾아보고 기록하게 하세요. 그러면 연결한 다른 모든 에이전트도 같은 노트를 보고, 나는 앱에서 노트를 읽고 편집할 수 있어요. 저희의 Claude Code 세컨드 브레인 가이드에서 Codex, Cursor, Claude Code가 각자의 지침 파일을 어떻게 읽는지 비교해요.

특별한 명령은 필요 없어요. 평소 말로 요청하면 Codex가 도구를 골라요. 다음은 읽기 전용부터 작고 구체적인 편집까지, 처음 해 보기 좋은 프롬프트예요.

> 내 Knowtarium 워크스페이스에서 뭘 할 수 있나요?
 
> 내 노트에서 가격 결정을 찾아서, 참고한 노트의 링크와
  함께 답해 주세요.
 
> meetings 폴더를 읽고 이번 주 요약을 새 노트로
  써 주세요. 회의 노트는 바꾸지 마세요.
 
> 오늘 통화 메모를 Acme 프로젝트 노트에 추가해 주세요.
  그 밖에는 아무것도 바꾸지 마세요.
 
> 내 인박스에 뭐가 있나요?
  클립마다 할 일을 하나씩 제안해 주세요.

첫 번째 프롬프트는 연결이 작동하는지 빠르게 확인하는 방법이에요. Codex가 워크스페이스 이름을 말하고, 변경이 즉시 저장되는지 승인을 기다리는지 알려 줘야 해요. 마지막 프롬프트는 웹 클리퍼로 저장한 클립을 읽어요. 처음 편집은 범위를 좁게 하고, 바뀌면 안 되는 것을 말해 주세요. 바뀐 노트 마흔 개보다 네 개를 검토하는 게 훨씬 쉬워요.

Codex의 모든 변경은 자신의 키로 서명되므로, 어떤 편집이 Codex의 것인지 항상 알 수 있어요.

• 사이드바의 점이 Codex가 편집한 노트를 열어 볼 때까지 표시하고, 워크스페이스 페이지는 그 노트들을 Edited by agents 아래에 나열해요.
• 노트 제목 아래 줄에 Codex가 편집했다고 표시되고, diff를 보는 See changes와 이전 버전을 되살리는 Undo가 있어요.
• 삭제, 이동, 폴더 변경은 워크스페이스 페이지의 Deleted and reorganized by agents 아래에 2주 동안(기록 보관 기간이 더 짧으면 그 기간 동안) Undo, Undo this agent's last 24 hours와 함께 나열돼요. 삭제된 노트는 기록 보관 기간 안이라면 되살릴 수 있어요.
• 기록은 하루에서 1년까지 내가 정한 기간 동안 모든 버전을 보관해요. 검토가 켜진 폴더에서는 변경이 대신 검토 대기열에서 기다려요.

(새 탭에서 원래 크기로 열림) (새 탭에서 원래 크기로 열림)

에이전트 편집 검토 가이드에는 에이전트가 바꾼 것을 믿기 전에 확인하는 루틴이 있어요.

Codex에서 Knowtarium이 보이지 않아요

Knowtarium을 추가한 뒤 Codex를 다시 시작하세요. 이미 실행 중이던 세션은 새 서버를 불러오지 않아요. 플러그인을 썼다면 /plugins에서 Knowtarium이 설치되어 있고 꺼져 있지 않은지 확인하세요.

에이전트 목록에 Codex가 없어요

CLI는 ~/.codex 폴더(또는 $CODEX_HOME)로 Codex를 찾아내요. Codex가 설정을 다른 곳에 보관한다면 그 터미널에서 CODEX_HOME을 설정하세요. 어느 경우든 Codex에 Knowtarium을 추가하려면 홈 폴더에서 npx knowtarium agents --agent codex를 실행하세요(플러그인을 쓴다면 실행하지 마세요).

Codex를 건너뛰었어요

config.toml이 유효한 TOML이 아니거나, MCP 서버가 CLI가 안전하게 편집할 수 없는 형태로 쓰여 있으면 CLI는 아무것도 쓰지 않고 그 이유를 알려 줘요. 서버 항목과 함께 "add it by hand" 줄도 출력하지만, 직접 쓴 항목은 프로젝트 폴더에서 npx를 실행하게 되므로 그 줄은 무시하세요. 파일을 고치거나(또는 다른 곳으로 옮기거나), 그다음 npx knowtarium agents --agent codex를 다시 실행하세요.

연결 확인하기

npx knowtarium status는 연결된 워크스페이스와 그 접근 권한, 변경 방식, 토큰, 로컬 캐시를 보여 주고, 키가 어디에 보관되는지 알려 줘요.

knowtarium이 업데이트하라고 해요

홈 폴더에서 npx knowtarium@latest agents를 실행하세요. 에이전트가 새 버전을 가리키게 해요. 그런 다음 Codex를 다시 시작하세요.

$ cd ~$ npx knowtarium@latest agents$ npx knowtarium status

플러그인을 쓴다면 마켓플레이스를 업그레이드하고(목록만 새로 고쳐요), 플러그인을 다시 추가해 새 버전을 설치한 뒤 Codex를 다시 시작하세요.

$ codex plugin marketplace upgrade knowtarium$ codex plugin add knowtarium@knowtarium

플러그인과 명령의 항목이 둘 다 있어요

이 경우 플러그인의 서버 대신 config.toml의 항목이 실행돼요. CLI는 이 항목을 최신으로 유지하고 그렇다고 알려 줘요. 플러그인의 서버를 쓰려면 ~/.codex/config.toml(또는 $CODEX_HOME 안의 파일)에서 [mcp_servers.knowtarium] 테이블을 제거하고 Codex를 다시 시작하세요.

저장될 줄 알았던 변경이 승인을 기다려요

Codex는 각 변경이 저장되었는지 제안되었는지, 그리고 그 이유를 알려 줘요. 폴더가 검토를 요구하거나, 워크스페이스 설정을 확인할 수 없었거나, 오늘의 직접 변경 한도에 도달했거나, 이 연결이 제안만 할 수 있는 경우예요. 마지막 경우라면 홈 폴더에서 npx knowtarium connect를 다시 실행한 뒤 Codex를 다시 시작하세요.