Cursor-Cortex: AI 어시스턴트를 위한 구조화된 메모리

Cursor, Claude Code 및 MCP 호환 AI 어시스턴트와 함께 작동합니다.

AI 어시스턴트의 기억 상실과 컨텍스트 혼란을 해결하세요. Cursor-Cortex는 AI가 실제로 소프트웨어를 구축하는 데 필요한 구조화된 사고와 장기 기억을 제공합니다.

🧠 AI 어시스턴트의 문제점

LLM 기반 AI 어시스턴트는 코드 생성과 개념 설명에 뛰어나지만 다음과 같은 문제가 있습니다:

• ❌ 기억 상실: "어제 우리 뭐 하고 있었지?"

• ❌ 컨텍스트 전환: "잠깐, 이 프로젝트가 뭐였지?"

• ❌ 에이전트 실패: 길을 잃거나, 환각을 일으키거나, 목표를 놓치는 경우

• ❌ 구조 부재: 체계적인 사고 없이 아이디어 사이를 오가는 경우

• ❌ 지식 격차: 회사별 또는 프로젝트별 인사이트에 접근할 수 없는 경우

결과: 실제 문제를 해결하는 것보다 컨텍스트를 설명하는 데 더 많은 시간을 소비하게 됩니다.

Related MCP server: BuildAutomata Memory MCP Server

🎯 Cursor-Cortex 솔루션

Cursor-Cortex는 AI에 구조화된 외부 메모리를 제공합니다:

📋 컨텍스트 파일 → "이 프로젝트는 무엇에 관한 것인가?"

AI는 항상 프로젝트 목표, 아키텍처 결정, 현재 초점을 알고 있습니다.

📝 브랜치 노트 → "우리는 무엇을 작업해 왔는가?"

AI가 중단한 지점부터 정확히 이어갈 수 있도록 지속적인 개발 로그를 제공합니다.

🧠 암묵적 지식 → "이런 유형의 문제를 어떻게 해결하는가?"

LLM이 알지 못하는 회사별 솔루션, 패턴, 그리고 힘들게 얻은 인사이트를 제공합니다.

✅ 체크리스트 → "우리의 체계적인 접근 방식은 무엇인가?"

AI(와 사용자)를 체계적이고 철저하게 유지하는 구조화된 사고 프레임워크입니다.

💡 도입 전 vs 도입 후

❌ Cursor-Cortex 없이:

You: "Help me continue the authentication work"
AI: "I need more context. What authentication system? What issues were you facing?"
You: "Ugh, let me explain everything again..."

✅ Cursor-Cortex 사용 시:

You: "Help me continue the authentication work"  
AI: *reads context + branch notes + knowledge base*
"I see you're implementing JWT refresh tokens and hit CORS issues yesterday. 
Based on our company knowledge doc about API security, let's check the middleware..."

🚀 핵심 이점

AI를 똑똑한 인턴에서 모든 것을 기억하고, 구조화된 사고를 따르며, 조직 지식에 접근할 수 있는 경험 많은 팀원으로 변화시키세요.

⚡ 전체 설정 가이드

1. 종속성 설치

npm install --legacy-peer-deps

참고: --legacy-peer-deps 플래그는 TensorFlow.js v3.x와 v4.x 버전 간의 피어 종속성 충돌로 인해 필요합니다.

2. 전체 경로 확인

pwd
# Copy the output - you'll need it for configuration

3. 벡터 검색 설정 (선택 사항)

AI 기반 의미 검색 기능을 위한 설정입니다:

시스템 요구 사항:

• Node.js 18+

• 2GB RAM (벡터 모델용)

• 500MB 디스크 공간

설정 단계:

# Step 1: Generate embeddings for all knowledge files
node generate-all-embeddings-cpu.js

# This creates vector embeddings for:
# - All tacit knowledge documents
# - All branch notes
# - All context files
# Duration varies by document count and system specs

# Step 2 (Optional): Force regenerate if content changes
node generate-all-embeddings-cpu.js --force

# Step 3 (Optional): View progress during generation
node generate-all-embeddings-cpu.js --verbose

이것이 중요한 이유:

• 임베딩이 없으면 의미 검색이 텍스트 검색으로 대체됩니다

• 사전 계산된 임베딩은 검색 속도를 100배 향상시킵니다

• 한 번 생성하면 모든 의미 검색에 사용할 수 있습니다

• 임베딩은 ~/.cursor-cortex/embeddings/에 저장됩니다

4. Cursor MCP 구성

~/.cursor/mcp.json 파일을 생성하거나 편집합니다:

"cursor-cortex": {
      "command": "node",
      "args": ["/YOUR/FULL/PATH/TO/cursor-cortex/index.js"],
      "tools": [
        "update_branch_note", 
        "add_commit_separator",
        "read_branch_notes",
        "update_context_file", 
        "read_project_context",
        "read_branch_context", 
        "list_context_files", 
        "generate_commit_message", 
        "generate_jira_comment", 
        "create_tacit_knowledge",
        "read_tacit_knowledge", 
        "search_branch_notes",
        "generate_embeddings",
        "create_completion_checklist",
        "read_checklist",
        "update_checklist",
        "sign_off_checklist",
        "archive_branch_note",
        "clear_branch_note",
        "list_all_branch_notes",
        "enhanced_branch_survey",
        "comprehensive_knowledge_search",
        "construct_project_narrative",
        "timeline_reconstruction",
        "context_sync_guidance",
        "analyze_documentation_gaps",
        "migrate_context_files",
        "request_critical_thinking_space",
        "check_critical_thinking_status",
        "request_thinking_guidance",
        "add_perspective",
        "request_synthesis_space",
        "request_synthesis_step_guidance",
        "complete_synthesis_step",
        "generate_context_zip",
        "unpack_context"
      ],
      "stdio": true,
      "env": {
        "DEBUG": "true"
      }
    },

/YOUR/FULL/PATH/TO/cursor-cortex/를 2단계의 출력으로 교체하세요

참고: 이 구성은 Cursor-Cortex v1.2.0+용입니다. 이전 버전을 사용하는 경우 일부 도구를 사용하지 못할 수 있습니다. package.json 버전을 확인하고 업데이트를 고려하세요.

5. Cursor 재시작

Cursor를 완전히 종료하고 다시 엽니다.

Claude Code 설치

프로젝트 루트(또는 전역적으로 ~/.claude/settings.json)에 .claude/settings.json 파일을 생성하거나 편집합니다:

{
  "mcpServers": {
    "cursor-cortex": {
      "command": "node",
      "args": ["/YOUR/FULL/PATH/TO/cursor-cortex/index.js"]
    }
  }
}

/YOUR/FULL/PATH/TO/cursor-cortex/를 2단계의 출력으로 교체한 후, Claude Code를 재시작하세요.

6. MCP 서버 활성화

1. Cursor 설정(Cmd/Ctrl + ,)으로 이동합니다

2. Features → Model Context Protocol로 이동합니다

3. cursor-cortex를 찾아 ON으로 전환합니다

4. Storage directory created at /Users/yourname/.cursor-cortex 메시지가 표시되어야 합니다

7. 테스트

아무 Cursor 채팅에서 다음을 시도하세요:

"Update my branch notes: Testing Cursor-Cortex setup"

작동하면 Successfully updated branch note with: "Testing Cursor-Cortex setup" 메시지가 표시됩니다.

8. 지식 탐색기 (시각적 그래프)

모든 설정이 완료되면 지식 기반을 대화형 네트워크 그래프로 탐색하세요:

npm run explorer

그런 다음 브라우저에서 **http://localhost:4000**을 엽니다.

기능:

• 3계층 시각화: 프로젝트, 브랜치 노트, 암묵적 지식을 상호 연결된 노드로 표시

• 유사성 기반 레이아웃: 임베딩 코사인 유사도를 사용하여 의미적으로 유사한 프로젝트를 클러스터링

• 신경 펄스 애니메이션: 지식 네트워크를 통해 신호가 실시간으로 전파되는 것을 확인

• 활동 기반 색상: 밝은 노드 = 최근에 업데이트된 프로젝트

• 클릭하여 탐색: 노드를 클릭하여 세부 정보, 유사 프로젝트, 태그를 확인

• 깊이 토글: 컴팩트(프로젝트만), 브랜치, 전체 보기 간 전환

🔧 문제 해결

일반적인 문제:

❌ "도구를 찾을 수 없음" 오류

• 구성 후 Cursor를 완전히 재시작하세요

• 설정에서 MCP 서버가 활성화되어 있는지 확인하세요

• mcp.json의 파일 경로가 올바른지 확인하세요 (오타 없이)

❌ MCP 구성이 작동하지 않음

• jsonlint.com에서 JSON 구문을 검증하세요

• 쉼표와 따옴표가 올바른지 확인하세요

• mcp.json의 파일 권한을 확인하세요

❌ 벡터 검색이 작동하지 않음

• npm install을 실행하여 TensorFlow.js가 설치되었는지 확인하세요

• 시스템에 2GB 이상의 RAM이 있는지 확인하세요

• 벡터 검색이 실패하면 텍스트 검색 모드를 시도하세요

도움이 필요하신가요? 빠른 지원을 위해 오류 메시지와 함께 이슈를 생성하세요.

9. 사용 시작

• "커밋되지 않은 작업 표시" - 작업 중인 내용을 확인합니다

• "커밋 메시지 생성" - 노트에서 커밋을 생성합니다

• "암묵적 지식 문서 생성" - 나중을 위해 솔루션을 저장합니다

📖 기본 사용법

생각 기록하기

코딩하면서 AI 어시스턴트에게 말하세요:

"Update branch notes: Fixed the login validation bug by adding proper error handling 
for expired tokens. Had to modify the JWT middleware."

방향 유지하기

작업으로 돌아올 때:

"Show me my uncommitted work"

스마트 커밋

커밋할 준비가 되면:

"Generate a commit message"

AI가 모든 노트를 읽고 "Fix JWT token validation and error handling"을 생성합니다

🏗️ 프로젝트 구조

Cursor-Cortex는 지식을 다음과 같이 구성합니다:

• 📝 브랜치 노트: 현재 작업 중인 내용

• 📋 컨텍스트 파일: 프로젝트 문서 및 결정 사항

• 🧠 지식 베이스: 향후 참조를 위한 솔루션 및 인사이트

• ✅ 체크리스트: 프로젝트 완료 추적

모든 데이터는 ~/.cursor-cortex/에 저장되며 AI를 통해 접근할 수 있습니다.

🎓 고급 사용자 기능

기본 기능에 익숙해지면 다음 고급 기능을 살펴보세요:

프로젝트 간 지식 검색

"Search all my projects for JWT authentication solutions"

자동 커밋 추적

node setup-hooks.js  # Auto-separates pre/post commit work

프로젝트 체크리스트

요구 사항, 테스트, 승인을 추적합니다:

"Create a completion checklist for the user auth feature"

팀 지식 공유

재사용 가능한 솔루션 문서를 생성합니다:

"Create tacit knowledge document about our JWT implementation approach"

지식 고고학 및 프로젝트 인텔리전스

프로젝트 지식을 분석하고 종합합니다:

"Survey all my branch documentation and show completeness scores"
"Construct a project narrative for the user authentication system"
"Show me a timeline of all development across projects"
"Analyze this folder structure for documentation gaps"

🛠️ 사용 가능한 모든 도구

• update_branch_note - 개발 로그에 항목 추가

• read_branch_notes - 기본값은 전체 파일(COMMIT 구분자 포함)입니다. 마지막 커밋 이후의 작업은 mode=uncommitted 또는 uncommittedOnly=true를 사용하고, 필터링을 위해 beforeDate, afterDate, commitHash를 선택적으로 사용할 수 있습니다.

• add_commit_separator - 커밋 경계 표시 (git 훅을 통해 자동)

• generate_commit_message - AI가 노트에서 커밋 생성

• update_context_file - 프로젝트 목표 및 결정 사항 문서화

• read_project_context - 브랜치와 무관한 프로젝트 컨텍스트만 읽기

• read_branch_context - 브랜치별 컨텍스트만 읽기

• list_context_files - 프로젝트 간 경고와 함께 모든 프로젝트 문서 탐색

• create_tacit_knowledge - 향후 참조를 위한 솔루션 문서화

• read_tacit_knowledge - 태그 및 내용 검색으로 모든 프로젝트의 지식 검색

• search_branch_notes - 의미 검색으로 프로젝트 간 브랜치 노트 검색

• generate_embeddings - 의미 검색을 위한 벡터 임베딩 생성 또는 재생성

• comprehensive_knowledge_search - 모든 Cursor-Cortex 지식에 대한 전역 의미 검색

• create_completion_checklist - 요구 사항 및 인도물 추적

• read_checklist - 진행 상황 보기

• update_checklist - 항목 완료 표시 (수동 또는 자동 감지)

• sign_off_checklist - 서명을 통한 공식 승인

• archive_branch_note - 완료된 작업 보관

• clear_branch_note - 브랜치 문서 초기화

• migrate_context_files - 기존 컨텍스트 파일을 스마트 하이브리드 컨텍스트 시스템으로 마이그레이션

• list_all_branch_notes - 우선순위 순서로 모든 프로젝트의 모든 브랜치 노트 보기

• enhanced_branch_survey - 완전성 점수 및 관계 매핑을 통한 문서 종합 분석

• construct_project_narrative - 흩어진 기술 세부 사항을 일관된 제작 스토리로 엮기

• timeline_reconstruction - 브랜치 노트 및 커밋 구분자에서 연대순 타임라인 데이터 추출

• context_sync_guidance - 타임라인 데이터를 기반으로 프로젝트 컨텍스트 동기화를 위한 상황별 지침 얻기

• analyze_documentation_gaps - 폴더 구조를 분석하여 문서화 필요 사항을 식별하고 체크리스트 자동 생성

• request_critical_thinking_space - 여섯 가지 사고 모자 방법론을 사용한 체계적인 분석 작업 공간 생성

• check_critical_thinking_status - 비판적 사고 분석의 완료 상태 확인

• request_thinking_guidance - 특정 여섯 가지 사고 모자 관점에 대한 지침 얻기

• add_perspective - 비판적 사고 작업 공간에 특정 관점 분석 추가

• request_synthesis_space - 통합을 위해 관점을 종합 작업 공간에 로드

• request_synthesis_step_guidance - 종합 단계에 대한 상세 지침 얻기

• complete_synthesis_step - 특정 종합 단계 완료 및 프로세스 업데이트

• generate_context_zip - 사용자/환경 간 공유를 위해 지식을 휴대용 ZIP 아카이브로 패키징

• unpack_context - 안전한 충돌 해결로 공유 컨텍스트 패키지 가져오기

🎛️ 고급 구성

Git 통합

자동 커밋 구분자는 MCP 서버가 실행 중이어야 합니다:

node setup-hooks.js  # Install git hooks

CLI 인터페이스

AI 없이 직접 접근:

node cursor-cortex-cli.js  # Interactive menu

🤝 기여

버그를 발견했거나 아이디어가 있으신가요? 이슈를 열거나 풀 리퀘스트를 제출하세요 — 기여는 언제나 환영합니다!

저자: Manuel Flores-Ramirez

📄 라이선스

이 프로젝트는 Parachute Public License (PPL) v1.0에 따라 라이선스가 부여됩니다.

PPL은 정부, 군사, 감시 및 기타 유해한 주체의 사용을 제한하는 윤리적 라이선스입니다. 전체 세부 사항 및 근거는 parachute.pub에서 확인하세요.

© 2025 Manuel Flores-Ramirez.