Codex는 장기 기억(Long-term memory)이 없습니다. 모든 세션은 깨끗한 상태로 시작됩니다. 프로젝트 구조, 명명 규칙(Naming conventions), 테스트 선호도, 그리고 지난 화요일에 API 설계에 대해 결정했던 내용 등을 매번 설명해야 합니다. 그러고 나서 터미널을 닫으면, 내일 다시 이 모든 과정을 반복해야 합니다.

해결책은 세션 간에 유지되는 메모리 계층(Memory layer)을 Codex에 제공하는 것입니다. 이 메모리를 저장하기에 가장 좋은 장소는 Obsidian입니다. 왜냐하면 Obsidian은 디스크에 저장된 단순한 마크다운(Markdown) 파일이기 때문입니다. 독점적인 데이터베이스도 없고, 제어할 수 없는 동기화 서비스도 없습니다. 모든 노트는 사용자가 직접 읽고, 편집하고, 검색하고, 버전 관리(Version control)를 할 수 있는 일반 텍스트 파일입니다.

저는 Codex의 메모리를 Obsidian에 연결하는 세 가지 서로 다른 접근 방식을 테스트했습니다. 각 방식은 문제를 다르게 해결하며, 올바른 선택은 사용자가 감수하고자 하는 설정의 양과 통합(Integration)의 깊이에 따라 달라집니다.

다음은 각 접근 방식과 실제 작동 방식, 그리고 처음부터 설정하는 방법입니다.

첫 번째: Codex 메모리가 실제로 작동하는 방식 이해하기

Obsidian에 무언가를 연결하기 전에, Codex에 이미 내장된 두 가지 메모리 계층을 이해해야 합니다.

계층 1: AGENTS.md (정적 지침, Static Instructions)

이것은 리포지토리(Repo)의 루트에 배치하는 마크다운 파일입니다. Codex는 작업을 수행하기 전 매 세션의 시작 단계에서 이 파일을 읽습니다. 이를 브리핑 문서라고 생각하면 됩니다. 프로젝트 컨벤션(Conventions), 테스트 명령, 디렉토리 레이아웃, 그리고 에이전트(Agent)가 매번 알아야 하는 모든 내용을 여기에 작성합니다.

AGENTS.md는 버전 관리 시스템에 체크인(Checked into)됩니다. 팀 전체가 공유합니다. 항상 적용되어야 하는 규칙을 위한 적절한 장소입니다.

여기에 들어갈 내용의 간단한 예시:

# AGENTS.md

## Project
...

Codex는 이를 자동으로 로드합니다. 별도의 설정은 필요하지 않습니다. 파일만 생성하면 됩니다.

또한 Codex 세션 내에서 /init을 실행하면, 프로젝트에서 감지된 기술 스택(Tech stack), 디렉토리 구조 및 설정 파일을 기반으로 AGENTS.md의 뼈대(Scaffold)를 만들어 줍니다. 처음부터 직접 작성하고 싶지 않다면 좋은 시작점이 될 것입니다.

주의할 점 한 가지: Codex는 저장소 루트(repo root)부터 현재 디렉터리까지의 AGENTS.md 파일들을 연결(concatenate)하며, 합계 크기가 32 KiB에 도달하면 중단됩니다. 만약 지침(instructions)이 무시되고 있다면, 이 크기 제한에 걸렸을 가능성이 있습니다. Codex에게 "Summarize the instructions you have loaded for this session."라고 질문하여 이를 확인할 수 있습니다.

Layer 2: 네이티브 메모리 (Native Memories, 자동 생성 방식)

이것은 더 최신 시스템입니다. 이 기능을 활성화하면 Codex가 백그라운드에서 세션 내용을 자동으로 요약하고, 해당 요약본을 ~/.codex/memories/에 기록합니다. 다음 세션을 시작할 때, Codex는 해당 요약본들을 다시 읽어 들입니다. 사용자가 무언가를 붙여넣거나 참조할 필요가 없습니다. 컨텍스트(context)가 그냥 나타납니다.

메모리 파이프라인(memory pipeline)은 두 단계로 작동합니다. 1단계(Phase 1)는 세션이 충분히 유휴 상태(idle)가 된 후(기본값 6시간, min_rollout_idle_hours 설정을 통해 1~48시간 사이로 구성 가능) 실행됩니다. 이 단계에서는 대화에서 핵심 컨텍스트를 추출하고, 발견된 비밀 정보(secrets)를 삭제(redact)한 뒤, 구조화된 요약본을 저장합니다. 2단계(Phase 2)는 이러한 개별 요약본들을 주기적으로 통합하여, 향후 세션에 주입(inject)될 하나의 통합 메모리 파일로 만듭니다.

~/.codex/memories/ 하위의 저장 구조는 다음과 같습니다:

~/.codex/memories/
├── memory_summary.md      # 모든 세션에 주입되는 상위 수준(High-level) 요약
├── MEMORY.md              # 집계된 통찰(insights)의 검색 가능한 레지스트리
...

활성화 방법:

# ~/.codex/config.toml
[features]
memories = true

또는 일회성 CLI 오버라이드(override)를 사용하여: codex -c features.memories=true

또는 Codex 앱에서: Settings > Memories > Enable.

활성화한 후에는 동작을 미세 조정(fine-tune)할 수 있습니다:

[memories]
generate_memories = true    # 새로운 스레드가 메모리 항목을 생성하도록 허용
use_memories = true         # 기존 메모리를 새로운 세션에 주입

이 설정들을 독립적으로 실행할 수도 있습니다. Codex가 이전 메모리는 읽되 새로운 메모리는 생성하지 않기를 원하시나요? 그렇다면 generate_memories = false로 설정하고 use_memories = true로 설정하십시오. 이는 디버깅을 하거나 메모리 상태를 고정(freeze)하고 싶을 때 유용합니다.

실행 중인 세션 내에서 /memories를 입력하면 해당 특정 스레드가 메모리를 사용하거나 생성할 수 있는지 여부를 제어할 수 있습니다. 이는 전역 설정(global settings)에는 영향을 주지 않습니다.

중요 주의사항: 네이티브 메모리(Native memories)는 기본적으로 꺼져 있으며, 현재 유럽경제지역(EEA), 영국 또는 스위스에서는 사용할 수 없습니다. 또한, 메모리는 사용자별로 적용됩니다. 만약 팀이 Codex 환경을 공유하더라도, 개별 메모리는 팀원 간에 통합되지 않습니다. 팀 전체의 컨텍스트(context)는 AGENTS.md에 포함되어야 합니다.

Obsidian의 역할

위의 두 계층도 작동하지만 한계가 있습니다. AGENTS.md는 정적(static)이며 수동적입니다. 네이티브 메모리는 자동 생성되지만 불투명하며 검색하기가 쉽지 않습니다. Obsidian은 에이전트가 읽고 쓸 수 있는 시각적이고 조직적이며 검색 가능한 지식 베이스(knowledge base)를 제공합니다. 또한 Obsidian은 단순히 마크다운(markdown) 파일로 구성된 폴더일 뿐이므로, 워크플로우 체인의 모든 도구와 원활하게 연동됩니다.

접근 방식 1: Basic Memory + MCP (가장 쉬운 설정, 도구 간 호환 가능)

이 방식은 Obsidian과 동기화되는 지속성 Codex 메모리를 구축하는 가장 빠른 경로입니다.

Basic Memory는 모든 AI 도구(Codex, Claude Code, Cursor, Claude Desktop)에 일반 마크다운 파일을 통해 지속적인 컨텍스트(context)를 제공하는 MCP 서버입니다. 사용자는 폴더에 노트를 저장합니다. Basic Memory가 이를 인덱싱(indexing)합니다. Codex는 MCP를 통해 이를 쿼리(query)합니다. 저장 형식이 단순한 마크다운이기 때문에, Obsidian이 동일한 폴더를 가리키도록 설정하면 모든 내용이 그래프 뷰(graph view), 백링크(backlinks), 검색 기능과 함께 사용자의 보관함(vault)에 나타납니다.

실제 적용 사례

API를 구축한 지 3주가 지났다고 가정해 봅시다. 당신은 인증 전략(auth strategy), 데이터베이스 스키마(database schema), 속도 제한(rate limiting) 방식, 에러 처리 패턴(error handling patterns)에 대한 결정을 내렸습니다. 이 모든 컨텍스트는 Basic Memory 노트에 저장되어 있습니다.

새로운 Codex 세션을 열고 다음과 같이 말합니다: "API 설계에 대해 우리가 내린 결정이 무엇인가요? 내 노트를 확인해 보세요."

Codex는 MCP를 통해 시맨틱 검색(semantic search)을 수행하여 프로젝트 전반에서 관련 노트를 찾아내고, 실제 프로젝트 이력에 근거하여 답변합니다. 다시 설명할 필요도, 이전 대화 내용을 붙여넣을 필요도 없습니다.

동일한 프로젝트에서 다른 작업을 위해 Claude Code로 전환하더라도, 동일한 노트와 동일한 컨텍스트를 그대로 유지하며 재설정할 필요가 전혀 없습니다.

설정 (로컬 (Local))

codex mcp add basic-memory bash -c "uvx basic-memory mcp"

이것이 설치의 전부입니다. 단 한 줄의 명령어로 끝납니다. uvx 방식은 의존성 해결 (dependency resolution)을 자동으로 처리하며 Basic Memory를 자식 프로세스 (child process)로 실행합니다.

특정 프로젝트로 범위를 제한하려면:

codex mcp add basic-memory bash -c "uvx basic-memory mcp --project your-project-name"

연결 상태를 확인하려면:

codex mcp list

basic-memory가 목록에 표시되어야 합니다.

설정 (클라우드 (Cloud), 원격 접속용))

클라우드 호스팅 메모리를 사용하려면 다음 단계를 따르세요:

1. app.basicmemory.com의 Settings > API Keys에서 API 키를 생성합니다.

2. 셸 프로필 (shell profile)에 추가합니다:

echo 'export BASIC_MEMORY_API_KEY=your-key-here' >> ~/.zshrc
source ~/.zshrc

3. Codex 설정에 추가합니다:

# ~/.codex/config.toml
[mcp_servers.basic-memory]
url = "https://cloud.basicmemory.com/mcp"
...

Obsidian 연결하기

Obsidian을 엽니다. 새로운 보관소 (vault)를 생성합니다. 해당 보관소를 Basic Memory 디렉토리(기본값은 ~/basic-memory 또는 프로젝트 폴더)로 지정합니다. 그것으로 끝입니다. AI가 작성한 것과 동일한 마크다운 (markdown) 파일들이 그래프 뷰 (graph view), 백링크 (backlinks), 그리고 풍부한 편집 기능을 갖춘 Obsidian에 나타납니다. 별도의 가져오기 (import)나 내보내기 (export) 단계가 필요 없습니다.

Obsidian에서 생성한 노트는 즉시 Codex에서 사용할 수 있습니다. Codex가 생성한 노트는 Obsidian에 나타납니다. 동일한 파일, 두 개의 인터페이스입니다.

이 접근 방식을 사용하는 경우

가장 빠른 설정을 원하고, (Codex뿐만 아니라) 여러 AI 도구를 사용하며, 메모리 노트를 Obsidian에서 탐색하고 편집할 수 있는 일반 마크다운 형식으로 유지하고 싶을 때 이 방식을 사용합니다.

접근 방식 2: AGENTS.md + Codex Hooks를 활용한 구조화된 Obsidian 보관소 (가장 깊은 통합)

이것은 파워 유저 (power-user)를 위한 옵션입니다. 제3자 메모리 계층을 사용하는 대신, AGENTS.md와 라이프사이클 훅 (lifecycle hooks)을 통해 Codex가 직접 읽을 수 있는 구조화된 Obsidian 보관소를 구축합니다.

아이디어는 간단합니다. 당신의 Obsidian 보관소(vault)가 프로젝트의 지식 베이스(knowledge base)가 되는 것입니다. AGENTS.md는 Codex에게 보관소가 어떻게 구성되어 있는지, 명명 규칙(naming conventions)은 무엇인지, 그리고 정보를 어디에서 찾아야 하는지를 알려줍니다. Codex hooks는 세션 시작 시 보관소의 컨텍스트(context)를 자동으로 주입하므로, 현재 상황을 다시 설명할 필요가 전혀 없습니다.

Basic Memory가 MCP를 통해 공유된 노트 저장소를 제공한다면, 이 접근 방식은 외부 의존성 없이 완전한 제어권을 제공합니다. 모든 것은 당신의 보관소에 머물며, 모든 것은 일반 마크다운(plain markdown) 형식이고, Codex는 이를 네이티브하게 읽습니다.

실제 적용 모습

보관소 디렉토리에서 터미널을 열고 Codex를 실행합니다. SessionStart 훅(hook)이 자동으로 실행되어 보관소의 인덱스 파일(index file)을 읽고, 활성 프로젝트, 최근 결정 사항, 진행 중인 작업의 요약본을 세션에 주입합니다. Codex는 당신이 단 한 마디를 입력하기도 전에 상황을 파악하고 있습니다.

당신이 "지난주에 캐싱 전략(caching strategy)에 대해 무엇을 결정했었지?"라고 말하면, Codex는 보관소 내의 결정 기록(decision records)을 읽고 당신의 노트에서 답변을 추출합니다.

하루 동안 당신이 생성하는 모든 노트는 YAML 프론트매터(frontmatter)와 함께 파일로 저장되고, 태그가 지정되며, 링크됩니다. 결정 기록, 프로젝트 노트, 아키텍처 문서 등 말이죠. Codex는 AGENTS.md에 정의된 구조를 따르며 일관되게 파일을 분류합니다.

보관소 구조

projects/          # 활성 프로젝트당 하나의 폴더
decisions/         # 아키텍처 및 설계 결정 기록
memory/            # Codex가 세션 전반에 걸쳐 읽는 지속성 컨텍스트(persistent context)
...

1단계: 보관소 루트에 AGENTS.md 생성하기

이것은 당신의 보관소를 위한 Codex의 운영 매뉴얼입니다. 다음은 실질적인 예시입니다:

# AGENTS.md

## Vault Structure
...

2단계: SessionStart 훅 설정하기

Codex 훅(hooks)을 사용하면 특정 라이프사이클 이벤트(lifecycle events)에서 스크립트를 실행할 수 있습니다. SessionStart 이벤트는 세션이 시작될 때 발생하며 컨텍스트를 자동으로 주입할 수 있습니다.

훅(Hooks)은 실험적인 기능이며 현재 Windows에서는 비활성화되어 있습니다. 먼저 기능 플래그(feature flag)를 활성화해야 합니다:

# ~/.codex/config.toml
[features]
codex_hooks = true

그 다음, 여러분의 보관소(vault) 내에 .codex/hooks.json 파일을 생성하세요:

{
  "hooks": {
    "SessionStart": [
...

구조는 다음과 같습니다: 키(key)로 이벤트 이름이 오고, 그 뒤로 매처 그룹(matcher groups)의 배열이 오며, 각 그룹은 matcher 정규 표현식(regex)과 hooks 배열을 포함합니다. SessionStart의 경우, 매처(matcher)는 세션이 어떻게 시작되었는지(startup 또는 resume)를 기준으로 필터링합니다. timeout은 초 단위이며, 생략할 경우 기본값은 600입니다. 명령어가 표준 출력(stdout)으로 쓰는 모든 일반 텍스트는 세션의 개발자 컨텍스트(developer context)로 주입됩니다.

이 방식은 여러분의 목표와 보관소 인덱스(vault index)를 읽은 다음, 모든 Codex 세션이 시작될 때 이를 컨텍스트로 주입합니다. Codex는 여러분이 단 한 단어를 입력하기도 전에 이를 확인하게 됩니다.

훅(hook)을 더 스마트하게 만들 수도 있습니다. 최근의 git 변경 사항을 가져오고, 지난 48시간 동안 수정된 노트를 스캔하여 요약된 브리핑을 생성하는 스크립트를 작성할 수 있습니다:

#!/bin/bash
# .codex/session-start.sh
echo "## Current Goals"
...

그 다음, 해당 스크립트를 가리키도록 훅을 업데이트하세요:

{
  "hooks": {
    "SessionStart": [
...

3단계: Obsidian에서 보관소 열기

동일한 폴더를 Obsidian 보관소(vault)로 엽니다. 모든 노트에 대한 그래프 뷰(graph view), 결정 사항과 프로젝트 간의 백링크(backlinks), 전체 텍스트 검색, 그리고 Codex가 작성하는 모든 것을 탐색할 수 있는 시각적 인터페이스를 사용할 수 있습니다. 파일은 동일하지만, 인터페이스는 두 개가 되는 것입니다.

4단계: 보관소 디렉토리에서 Codex 실행하기

cd ~/your-vault && codex

Codex가 AGENTS.md를 로드하고, SessionStart 훅이 실행되어 여러분의 목표와 인덱스를 주입하면, 첫 번째 프롬프트부터 전체 컨텍스트를 가진 상태로 작업할 수 있습니다.

이 방식이 다른 접근 방식과 차별화되는 점

외부 도구가 필요 없습니다. MCP 서버도 필요 없습니다. API 키도 필요 없습니다. 모든 것은 AGENTS.md(지침), 훅(자동화), 그리고 마크다운(markdown) 파일(지식)로 이루어집니다. 보관소는 완전히 휴대 가능합니다. git으로 버전 관리를 할 수도 있고, 원하는 방식으로 동기화할 수도 있으며, 나중에 아무것도 다시 구축할 필요 없이 다른 에이전트(agent)로 전환할 수 있습니다. 마크다운으로 잘 문서화된 보관소는 특정 AI 도구에 종속되지 않습니다.

이 접근 방식을 사용해야 하는 경우

외부 의존성 없이 Obsidian을 워크플로우의 중심으로 사용하고 싶은 경우입니다. Codex가 무엇을 보고 보관소(Vault)가 어떻게 구성되는지를 정확하게 제어하고 싶은 경우입니다. 또한 AGENTS.md 파일과 간단한 훅 스크립트(Hook script)를 작성하는 데 익숙한 경우에 적합합니다.

접근 방식 3: 네이티브 메모리 + 수동 Obsidian 동기화 (최소한의 설정, 대부분의 사용자에게 충분함)

추가적인 설치를 원하지 않는다면, Codex의 내장 메모리 시스템(Built-in memory system)을 사용하고 Obsidian이 해당 메모리 폴더를 가리키도록 설정하기만 하면 됩니다.

이것은 가장 간단한 접근 방식입니다. 네이티브 메모리(Native memories)를 활성화하여 Codex가 요약본을 자동으로 생성하게 하고, ~/.codex/memories/를 Obsidian 보관소(Vault)로 열거나(또는 기존 보관소 내부의 폴더로 추가) 하세요. 이렇게 하면 Codex가 기억하는 모든 내용에 대해 시각적인 브라우징과 검색이 가능해집니다.