OpenContext 컨텍스트 관리 (Persistent Memory)

AI 어시스턴트에게 영구 메모리를 부여하세요. 반복 설명을 멈추고, 더 스마트하게 빌드하세요.

When to use this skill

세션 간 컨텍스트 유지가 필요할 때
프로젝트 배경/결정사항을 기록해야 할 때
이전 결론/교훈을 검색해야 할 때
Multi-Agent 워크플로우에서 지식 공유가 필요할 때
반복적인 배경 설명을 줄이고 싶을 때

1. 핵심 개념

문제점

AI 어시스턴트로 작업할 때 컨텍스트가 손실됩니다 (세션, 레포, 날짜 간). 배경 설명을 반복하고, 결정을 다시 설명하며, 때때로 어시스턴트가 잘못된 가정으로 계속 진행합니다.

해결책

OpenContext는 AI 어시스턴트를 위한 경량 개인 컨텍스트/지식 저장소입니다.

[컨텍스트 로드] → [작업 수행] → [결론 저장]

기본 경로

항목	경로
Contexts	`~/.opencontext/contexts`
Database	`~/.opencontext/opencontext.db`

2. 설치 및 초기화

CLI 설치

npm install -g @aicontextlab/cli
# 또는 npx 사용
npx @aicontextlab/cli <command>

초기화 (레포 내에서 실행)

cd your-project
oc init

oc init 수행 작업:

글로벌 컨텍스트 저장소 준비 (최초 실행 시)
선택한 도구에 대한 user-level commands/skills + mcp.json 생성
레포의 AGENTS.md 갱신

3. Slash Commands

초보자 친화 명령어

Command	용도
`/opencontext-help`	어디서 시작할지 모를 때
`/opencontext-context`	(기본 권장) 작업 전 배경 로드
`/opencontext-search`	기존 문서 검색
`/opencontext-create`	새 문서/아이디어 작성
`/opencontext-iterate`	결론 및 인용 저장

설치 위치

# Slash Commands
Cursor:      ~/.cursor/commands
Claude Code: ~/.claude/commands

# Skills
Cursor:      ~/.cursor/skills/opencontext-*/SKILL.md
Claude Code: ~/.claude/skills/opencontext-*/SKILL.md
Codex:       ~/.codex/skills/opencontext-*/SKILL.md

# MCP Config
Cursor:      ~/.cursor/mcp.json
Claude Code: ~/.claude/mcp.json

4. 핵심 CLI 명령어

폴더/문서 관리

# 폴더 목록 조회
oc folder ls --all

# 폴더 생성
oc folder create project-a -d "My project"

# 문서 생성
oc doc create project-a design.md -d "Design doc"

# 문서 목록 조회
oc doc ls project-a

검색 & 매니페스트

# 검색 (키워드/하이브리드/벡터)
oc search "your query" --mode keyword --format json

# 매니페스트 생성 (AI가 읽을 파일 목록)
oc context manifest project-a --limit 10

검색 모드

모드	설명	요구사항
`--mode keyword`	키워드 기반 검색	임베딩 불필요
`--mode vector`	벡터 검색	임베딩 + 인덱스 필요
`--mode hybrid`	하이브리드 (기본값)	임베딩 + 인덱스 필요

임베딩 설정 (시맨틱 검색용)

# API Key 설정
oc config set EMBEDDING_API_KEY "<<your_key>>"

# (선택) Base URL 설정
oc config set EMBEDDING_API_BASE "https://api.openai.com/v1"

# (선택) 모델 설정
oc config set EMBEDDING_MODEL "text-embedding-3-small"

# 인덱스 빌드
oc index build

5. MCP Tools

OpenContext MCP Tools

oc_list_folders    # 폴더 목록 조회
oc_list_docs       # 문서 목록 조회
oc_manifest        # 매니페스트 생성
oc_search          # 문서 검색
oc_create_doc      # 문서 생성
oc_get_link        # 안정적 링크 생성

Multi-Agent 통합

# Gemini: 대용량 분석
ask-gemini "전체 코드베이스 구조 분석해줘"

# Codex: 명령 실행
shell "docker-compose up -d"

# OpenContext: 결과 저장
oc doc create project-a conclusions.md -d "분석 결론"

6. Multi-Agent 워크플로우 통합

Orchestration Pattern

[Claude] 계획 수립
    ↓
[Gemini] 분석/리서치 + OpenContext 검색
    ↓
[Claude] 코드 작성
    ↓
[Codex] 실행/테스트
    ↓
[Claude] 결과 종합 + OpenContext 저장

실전 예시: API 설계 + 구현 + 테스트

# 1. [Claude] 스킬 기반 API 스펙 설계
/opencontext-context   # 프로젝트 배경 로드

# 2. [Gemini] 대용량 코드베이스 분석
ask-gemini "@src/ 기존 API 패턴 분석"

# 3. [Claude] 분석 결과 기반 코드 구현
# (OpenContext에서 로드한 컨텍스트 활용)

# 4. [Codex] 테스트 및 빌드
shell "npm test && npm run build"

# 5. [Claude] 최종 리포트 생성 + 결론 저장
/opencontext-iterate   # 결정사항 및 교훈 저장

7. 권장 일일 워크플로우

작업 전 (1분)

/opencontext-context

프로젝트 배경 + 알려진 함정 로드

작업 중

/opencontext-search

불확실할 때 기존 결론 검색

작업 후 (2분)

/opencontext-iterate

결정사항, 함정, 다음 단계 기록

고ROI 문서 유형

Acceptance Criteria - 수락 기준
Common Pitfalls - 자주 발생하는 함정
API Contracts - API 계약
Dependency Versions - 의존성 버전

8. 안정적 링크 (Stable Links)

문서 ID 기반 참조로 이름/이동에도 링크 유지:

[label](oc://doc/<stable_id>)

CLI로 링크 생성

oc doc link <doc_path>

MCP로 링크 생성

oc_get_link doc_path="Product/api-spec"

9. Desktop App & Web UI

Desktop App (권장)

네이티브 UI로 컨텍스트 관리/검색/편집
CLI 없이 사용 가능
자동 인덱스 빌드 (백그라운드)

인용 기능:

액션	방법	효과
텍스트 스니펫 인용	텍스트 선택 → 우클릭 → "Copy Citation"	Agent가 스니펫 + 출처 읽음
문서 인용	문서 제목 옆 인용 아이콘 클릭	Agent가 전체 문서 + stable_id 획득
폴더 인용	폴더 우클릭 → "Copy Folder Citation"	Agent가 폴더 내 모든 문서 일괄 읽음

Web UI

oc ui
# 기본 주소: http://127.0.0.1:4321

Quick Reference

필수 워크플로우

작업 전: /opencontext-context (배경 로드)
작업 중: /opencontext-search (검색)
작업 후: /opencontext-iterate (저장)

핵심 CLI 명령어

oc init              # 프로젝트 초기화
oc folder ls --all   # 폴더 목록
oc doc ls <folder>   # 문서 목록
oc search "query"    # 검색
oc doc create ...    # 문서 생성

MCP Tools

oc_list_folders  폴더 목록
oc_list_docs     문서 목록
oc_search        검색
oc_manifest      매니페스트
oc_create_doc    문서 생성
oc_get_link      링크 생성

경로

~/.opencontext/contexts      컨텍스트 저장소
~/.opencontext/opencontext.db  데이터베이스

opencontext