NeuralMind: AI 코딩 에이전트를 위한 영구적인 코드베이스 메모리

🧠 NeuralMind

PyPI version

Downloads

CI

Self-benchmark

License: MIT

tier2: source-available

Python 3.10+

Local-First

AI 코딩 에이전트를 위한 영구적인 코드베이스 메모리 — Claude Code, Codex, Cursor, Cline, Continue 및 모든 MCP 클라이언트.

사용자의 에이전트가 시니어 엔지니어가 하는 방식대로 코드베이스를 학습합니다. 즉, 무엇이 함께 사용되는지, 다음에 보통 어떤 부분을 건드리는지를 기억하며 세션 간에 이를 유지합니다. 로컬 우선(Local-first)이며 텔레메트리 전송 기능은 없습니다. 그 결과: 코드를 모든 소스 파일로 붙여넣는 것보다 훨씬 저렴한 코드 질문이 가능해집니다. **public benchmark**에서 매번 놓치는 경우를 공개하는 40개의 쿼리 중 40개에서 골드 파일을 찾아내며, 더 큰 150개 문항의 평가 중 93.3%에서 상위 5위에 들고, 그중 10개의 놓친 경우도 공개합니다.

설치 후, 사용자의 에이전트는 다음과 같은 기능을 수행합니다:

• SYNAPSE_MEMORY.md (학습된 연관성, 가장 강력한 허브 파일)로 부팅됩니다.
• 사용자가 보낸 각 프롬프트에 대해 관련 파일을 검색합니다 (Claude Code의 UserPromptSubmit 훅; Hermes-Agent에서는 플러그인의 pre_llm_call 훅, v4.9.0+): 새로운 인덱스에서 첫 번째 프롬프트를 보내면, 해당 프롬프트와 일치하는 파일과 심볼, 라인 번호, 그리고 시냅스 그래프가 연결된 코드를 가져옵니다. 또한, "예"나 주제와 관련 없는 질문 같은 대부분의 답변처럼 코드 내에서 프롬프트의 최적 매칭 점수가 임계값(cutoff) 미만일 때는 아무것도 추가하지 않습니다 (v4.11.0+).
• Claude Code가 세션을 압축한 후, 자체 첫 프롬프트, 최신 프롬프트 및 수정된 파일을 되돌려 받으며, 최대 200자까지 작성된 프롬프트를 처리합니다 (v4.11.0+).
• 코드베이스를 약 50,000 토큰 대신 약 800 토큰으로 질의합니다.
• 상태 점검(health checks), 시냅스 가지치기(synapse pruning), 감사 쿼리(audit queries), 그리고 코드/문서 유형 필터링을 수행합니다 (v3.1.4+).
• 변경 사항이 동료들이 공유하는 패턴을 건너뛸 때 pre-commit 경고를 받습니다. 이는 다른 열 개의 핸들러가 가지고 있는 인증 확인(auth check)을 잊은 열한 번째 핸들러입니다 (v3.2.0+).
• 실제로 신뢰할 수 있는 규정 준수 주석(compliance annotations)을 받습니다. 버전 문자열이나 SVG 경로는 더 이상 SOC 2 통제 항목으로 보고되지 않습니다 (v3.3.0+).
• 산문(prose)도 검색합니다: ingest-content는 책이나 문서 트리를 자체 프로젝트에 인덱싱하고, 변경된 내용만 재임베딩하며, 작업하는 동안 예상 완료 시간(ETA)이 표시되는 진행률 표시줄을 보여줍니다 (v3.4.0+).
• 코드뿐만 아니라 사용자의 두뇌로 생각합니다: 6가지 SOTA(State-of-the-Art) 시냅스 학습 기술(STC, SAMPL, resource STDP, FOK, lateral inhibition, replay)과 더불어 의도 인식 순위 지정 기능이 있어 "X는 Y를 어떻게 구현하는가"라는 질문을 코드에 대한 질문으로 해석하고, 문서 문자열(docstrings)보다 실제 구현 내용을 우선순위에 둡니다 (v3.9.0+; v4.12.0 이후로는 단어의 구성을 통해 감지된 의도가 더 이상 매칭 결과를 재가중하지 않으며, 사용자가 요청하는 유형만 그렇게 합니다. NEURALMIND_AUTO_INTENT_BOOST=1을 설정하면 이전 동작이 복원됩니다).

• v4.16.0 신규 기능: security.profile: cui는 다음을 하나의 설정으로 활성화합니다: OS 계정 식별자(OS-account identity), 암호화되지 않은 디스크에서의 실행 거부, 루프백 외부 또는 토큰 없이 serve 거부(이 방식으로 시작된 데몬은 프로젝트를 거부함), 그리고 LLM 문서화 시딩(documentation seeding) 거부(설정으로 전환해도 마찬가지). 각 거부는 감사 로그(audit log)에 기록되며, 모순되거나 철자가 틀린 프로필은 닫힘 실패(fails closed)로 처리됩니다. 또한 neuralmind doctor가 이를 단위로 확인하며, OS FIPS 모드가 꺼져 있으면 실패합니다 (release notes, CUI enclave walkthrough).
• v4.16.0 추가 기능: neuralmind team … 및 neuralmind onboarding은 실패 시 1을 반환합니다. 따라서 set -e 아래의 프로비저닝 스크립트는 다음 경우에 라이선스 거부로 인해 중단됩니다: 만료되거나 변경된 파일에서의 team license activate, 좌석 제한, 비관리자 계정, 손상된 감사 체인, 거부된 라이선스 계약. 이전에는 실패 내용을 출력하고 0을 반환하며 종료했지만, 이제 team seats sync는 좌석 제한이 매니페스트의 일부 좌석을 거부할 경우 2를 반환합니다 (release notes).
• v4.16.0 추가 기능: 결정(decision) 트레일러가 에이전트에게 도달하는 방식이 역전됩니다. Decision: git 트레일러는 각 프롬프트에 붙으며 (Claude Code 및 Hermes), 커밋 메시지는 변경할 수 없기 때문에 철회될 수 없습니다. 이제 neuralmind decisions scan (커밋 후 훅; 업데이트하려면 neuralmind init-hook . 재실행)이 이를 결정 스토어(decision store)로 가져오고, decisions invalidate <id>는 이후의 모든 프롬프트 중 하나를 제거하며, 클론된 저장소에서 실행되는 neuralmind why와 나중에 파일이 변경된 커밋은 사용자가 restore하거나 무효화할 때까지 [STALE: …]로 표시합니다 (release notes, walkthrough).
• v4.15.1: 만료된 Team 라이선스는 라이선스 계약이 부여하는 전체 30일의 유예 기간을 만료 날짜부터 계산하여 받게 됩니다.

v4.15.0은 NeuralMind가 마지막으로 실행된 시점에 따라 더 일찍 종료되거나 아예 종료되지 않을 수 있습니다. 시간을 되돌린 경우에도 여전히 아무것도 가져오지 못합니다. 아무것도 읽지 않던 self_hosted.offline_grace_days 설정이 사라졌습니다 (릴리스 노트)

• v4.15.0: neuralmind scan-for-secrets는 발견된 각 항목을 한 번만 보고하며, 해당 파일이 git에 추적되는지 여부를 알려줍니다. 체크아웃 내의 연결된 작업 트리(.worktrees/<id>/, .claude/worktrees/<id>/)는 더 이상 모든 발견 사항을 반복하지 않습니다. git 저장소 내부에서 스캔은 build가 인덱싱하는 것을 다루므로, .gitignore에 포함된 .env 파일은 --include-ignored를 전달하지 않는 한 보고되지 않으며, 보고서에는 무시된 파일의 개수와 건너뛴 작업 트리가 명시됩니다. 각 줄에는 크리덴셜이 이미 git 히스토리에 있는 경우 가장 먼저 순환시켜야 할 항목임을 나타내어 [tracked] 또는 [untracked]로 표시됩니다. 종료 코드는 변경되지 않았습니다 (릴리스 노트)
• v4.14.0: 신뢰하기보다는 학습을 확인하세요. neuralmind eval . --synapse-ab는 사용자의 자체 골드 질문(gold questions)을 읽기 전용으로 두 번 실행하며, synapse 리콜(recall) 기능을 켜고 끄면서 테스트하고, 순위가 올라가거나 내려간 질문들을 보고하며, hit@5의 승패를 정확한 McNemar p-value와 함께 보고하고, 읽은 레이어의 크기를 보고합니다. 이 스위치는 모든 빌드 시드에서 호출 및 import 엣지(edges)뿐만 아니라 사용 패턴이 학습시킨 것까지 포함하므로, 새로운 빌드는 이미 다를 수 있습니다. 각 실행은 사용 학습된 카운트(LTP edges, transitions)와 함께 기록되며, eval --report는 그 간격이 커지는지 여부를 보여줍니다. Hermes 플러그인은 이제 프로젝트 내부에서 읽는 파일로부터 편집뿐만 아니라 전환(transitions)을 학습합니다. 그리고 공개된 수치들은 측정하지 않는 것들을 말해줍니다: 전체 파일 비율 외에도, 벤치마크에서는 ripgrep이 상위 다섯 개 파일을 여는 경우를 인용했습니다 (토큰 수가 31–67배 적음; ripgrep은 40개 중 32개에서 골드 파일을 발견함), 그리고 작업 결과가 측정되지 않음을 명시합니다 (릴리스 노트)
• v4.14.0에서도: 검증할 수 있는 릴리스를 제공합니다.

컨테이너 이미지는 서명(cosign, keyless)되며, 이미지, wheel 및 sdist는 GitHub 빌드 증거(build-provenance attestations)를 포함합니다. 릴리스 워크플로우는 :latest로 이동하기 전에 이 두 가지 모두를 검증합니다. CI는 모든 변경 사항에 대해 bandit와 pip-audit 스캔을 수행하며, security/neuralmind.openvex.json 파일은 적용되지 않는 의존성 권고(dependency advisories)를 OpenVEX 형태로 게시합니다. docs/compliance/SSDF.md는 모든 NIST SP 800-218 (SSDF) 실무 지침을 증거와 매핑하며, 연방 구매자 인증(federal buyer's attestation)을 제공합니다 (release notes)

• v4.13.0: 인덱스는 로컬 커밋뿐만 아니라 git pull, 병합(merges), 브랜치 전환(branch switches) 및 리베이스(rebases) 후에도 최신 상태를 유지합니다: neuralmind init-hook은 post-merge, post-checkout 및 post-rewrite 훅을 추가합니다. 이들은 설치 시 발견되는 neuralmind (PATH로 폴백)를 호출하므로, GUI 클라이언트와 서비스 관리자도 재빌드를 트리거합니다. 재빌드는 백그라운드에서 실행되므로 git은 기다리지 않습니다 (--sync는 이전 동작을 유지). 또한 빌드된 프로젝트만 재빌드하므로 훅을 공유하는 임시 작업 디렉터리(throwaway worktrees)는 그대로 둡니다. 이들을 얻으려면 neuralmind init-hook .를 다시 실행하세요. 또한: 모든 쿼리와 빌드는 텍스트 없이 neuralmind metrics에 카운트됩니다 (최근 쿼리, 시냅스 성장, 일별 카운트). 각 MCP 호출의 감사 이벤트는 이를 수행한 클라이언트를 명시합니다 (neuralmind audit recent). 아무도 읽지 않는 남겨진 graphify-out/graph.json은 모든 빌드에서 그리고 doctor에 의해 이름이 지정됩니다 (neuralmind build . --archive-graphify가 이를 폐기). 그리고 query --explain --json는 설명을 유지합니다. 각 빌드는 이전 빌드 이후 시냅스 레이어의 성장 정도를 보여주며 (stats는 주간 데이터를 보여줌), 전환이 없는 경우에도 전환이 어디서 왔는지에 대한 선을 표시합니다; .neuralmind.yaml의 stale_after: 30m은 health와 doctor가 인덱스가 얼마나 뒤처졌는지 기준으로 게이트를 설정하게 하며, doctor는 드리프트 날짜를 기록합니다 (최신 수정일 2시간 전).
• v4.12.1: 문서화된 대로 검사에 실패할 경우 neuralmind doctor는 다시 1을 반환합니다. 따라서 neuralmind doctor .

&& …와 CI 단계에서 이를 게이트할 수 있습니다(v0.55.0부터 v4.12.0까지 항상 0을 반환; 경고는 여전히 0을 반환합니다). 인덱스가 재구축되면 더 이상 남아 있는 index.tvim.stale 백업은 turbovec 검사를 실패하지 않습니다: doctor가 변경하지 않고 라이브 인덱스를 로드합니다. 예제 스크립트(examples/, demos/, samples/)는 이제 자신이 시연하는 코드보다 낮은 순위를 차지하게 되었습니다. 이는 v4.12.0 이후 테스트 파일에 해당하며, 질문이 예제를 요청하지 않는 한 그렇습니다: pallets/click의 경우 루트에서 인덱싱되었을 때 14개 질문 중 4개가 이를 시작으로 했고, hit@1은 6개에서 14개 중 9개로 증가했습니다 (NEURALMIND_EXAMPLE_FILE_FACTOR=1` 설정 시 비활성화) (릴리스 노트)

• v4.12.0: 이제 쿼리가 4개 대신 8개의 검색 결과를 반환하며, 이는 상위 20개 후보 풀로 재순위화된 후 8개로 잘린 것입니다. 이 결과들은 파일 전반에 걸쳐 분산되어 있어 하나의 파일이 모든 슬롯을 차지할 수 없습니다. 테스트 파일은 질문에서 테스트에 대해 요청하는 경우가 아니라면 테스트하는 코드보다 낮은 순위를 차지합니다. L2는 해당 쿼리의 다른 후보 목록을 보여주며, 각 클러스터의 처음 일곱 노드만 보여주지 않습니다. 부스트가 더 이상 순위에 영향을 주지 않습니다: 코드 또는 문서 재가중치는 유형을 요청할 때(--type, MCP query_type)에만 적용되며, 코드 신호 부스트는 비활성화되고 키워드 검색은 질문 단어를 무시합니다. 노드는 해당 자격 이름(qualified name), 모듈 및 docstring으로 임베딩되므로 코드를 이동시켜도 더 이상 재임베딩되지 않습니다. JavaScript 저장소(.js, .mjs, .cjs, .jsx)는 코드 노드를 얻습니다. 150개 질문 검색 평가에서 hit@5는 컨텍스트 토큰이 11% 적을 때 80.0%에서 93.3%로 증가했습니다 (21개 질문 승리, 1개 패배). 공개 벤치마크에서는 모든 파일을 붙여넣었을 때보다 51–242배 적은 토큰으로 40개 중 40개의 쿼리에서 골드 파일이 발견되었습니다 (v4.11.1은 3개를 놓침). 발표된 손실: 더 큰 평가는 여전히 150개 중 10개를 놓치며, flask 및 rich의 경우 NeuralMind는 여전히 일반 벡터 기준선(MRR 0.72 대 0.74, 0.83 대 0.94)보다 골드 파일을 낮은 순위에 배치합니다.

Synapse는 더 이상 조회(lookup)마다 전체 엣지 테이블을 스캔하지 않으며, 네 개의 라이브러리 저장소에서는 query p50이 13–14ms였고 이 19.9k 노드 저장소에서는 21ms였습니다 (이전에는 한 대의 기계에서 266–348ms). 업그레이드 후 neuralmind build를 한 번 실행하세요: 모든 노드가 한 번 재임베딩됩니다. NEURALMIND_L3_K, NEURALMIND_L3_POOL, NEURALMIND_L3_FILE_DECAY, NEURALMIND_TEST_FILE_FACTOR 및 NEURALMIND_QUERY_LAYERS를 조정하세요 (릴리스 노트).

• v4.12.0에서도: --redact-secrets 옵션을 켜면, turbovec 백엔드가 마크다운 섹션의 본문을 저장하기 전에 (벡터 스토어와 키워드 인덱스에 비식별화된 상태로 도달했더라도) 자동으로 비식별화합니다. 또한 주입된 임베더(embedder)의 대규모 배치에서 MiniLM 벡터가 섞이는 현상이 사라졌습니다 (릴리스 노트).
• v4.12.0에서도: ChromaDB가 고정된(pinned) 프로젝트(backend: graph 또는 chroma)에서, neuralmind build는 더 이상 빈 .neuralmind/neuralmind_turbovec/store.sqlite 파일을 남기지 않으며, neuralmind doctor는 이 빈 스토어를 호환 가능하다고 호출하는 대신 Turbovec 호환성 검사를 해당 사항 없음(not applicable)으로 보고합니다. Turbovec 프로젝트는 이전과 같이 확인됩니다 (릴리스 노트).
• v4.11.0: 프롬프트 시간 검색(prompt-time recall)은 프롬프트의 최적...