Pindoc

AI 보조 개발을 위한 코드 고정형 팀 메모리. 에이전트는 지속 가능한 기록을 작성하고, 인간은 이를 검토, 논의 및 조정합니다.

Pindoc은 AI 코딩 에이전트와 협업하는 팀을 위한 자체 호스팅 프로젝트 메모리 시스템입니다. 에이전트가 발견한 유용한 정보를 결정, 디버깅 경로, 작업 완료, 검증 노트, 코드 연동 분석과 같은 유형별 아티팩트로 변환합니다. 모든 아티팩트는 프로젝트 영역별로 범위가 지정되며 커밋, 파일, URL, 리소스 또는 관련 Pindoc 아티팩트에 고정됩니다.

여전히 직접 입력할 필요가 없는 위키이지만, 자동화 자체가 목적은 아닙니다. Pindoc은 팀원과 미래의 에이전트가 재사용할 수 있는 에이전트 작업의 핵심 부분을 보존합니다.

존재 이유

AI 코딩 세션은 생산적이지만, 팀의 맥락은 여전히 다음과 같은 이유로 유실됩니다:

• 디버깅 경로가 터미널 세션 종료와 함께 사라짐,

• 동일한 결정 사항을 새로운 에이전트에게 매번 다시 설명해야 함,

• 유용한 분석 결과가 팀의 지식이 되지 못하고 특정 작업자의 채팅창에만 머묾,

• 위키, 이슈 트래커, PR, 커밋 메시지 전반에 중복 문서가 쌓임,

• 실제 프로젝트 환경에서는 문제를 발견한 사람이 즉시 코드를 수정할 수 없는 경우가 많음; 구조화된 증거는 팀이 논의하고 결정하는 데 도움을 줌.

Pindoc은 보존할 가치가 있는 에이전트 작업을 검색 가능하고 코드에 고정된 팀 메모리로 변환합니다. 다음 팀원이나 코딩 에이전트는 수정 작업을 수행하기 전에 Pindoc을 통해 중요한 내용을 확인할 수 있습니다.

Pindoc의 차별점

• 협업 메모리 계층: 아티팩트는 개인적인 채팅 요약이 아닌, 팀원과 미래의 에이전트를 위해 작성됩니다.

• 에이전트 전용 쓰기 인터페이스: Reader UI는 읽기 및 검토용이며, 영구적인 기록은 에이전트를 통해 이루어집니다.

• MCP 네이티브 워크플로우: pindoc.context_for_task, pindoc.artifact.propose, pindoc.task.queue와 같은 도구는 단순한 CRUD API가 아니라 에이전트의 동작을 제어합니다.

• 유형별 아티팩트: 결정(Decision), 분석(Analysis), 디버그(Debug), 흐름(Flow), 작업(Task), TC, 용어집(Glossary) 및 도메인 팩 유형.

• 코드 고정형 메모리: 아티팩트는 커밋, 파일, 코드 라인 범위, 리소스, URL 및 관련 아티팩트를 가리킬 수 있습니다.

• 기록 가치 중심 설계: Pindoc은 원시 채팅 기록을 피하고 결정, 분석, 디버그 경로, 검증 및 미래 가치가 있는 작업 맥락만 보존합니다.

• 멀티 프로젝트 데몬: 하나의 /mcp 엔드포인트로 여러 프로젝트를 지원하며, 각 도구 호출은 project_slug를 포함합니다.

• 자체 호스팅 우선: Docker Compose를 통해 Postgres, pgvector, Pindoc 데몬 및 Reader SPA를 실행할 수 있습니다.

공개 데모

읽기 전용 공개 데모는 추후 제공될 예정이며 현재 오픈 소스 릴리스에는 포함되어 있지 않습니다. 출시 전까지는 README, docs/ 및 자체 호스팅 클론이 주요 증거 자료입니다. Pindoc을 전체적으로 평가하려는 사용자는 docker compose up -d --build를 실행하여 자신의 아티팩트를 직접 확인해 볼 수 있습니다.

후속 데모 계획은 호스팅 인스턴스가 준비되었을 때 Public Demo Plan에서 확인할 수 있습니다.

빠른 시작

사전 요구 사항:

• Docker 27 이상

• 로컬 테스트 또는 소규모 팀 사용 시 CPU 2코어 및 RAM 4GB 권장

• Docker 이미지, Postgres 데이터 및 임베딩 캐시를 위해 5GB 이상의 여유 디스크 공간 권장; 초기 클론 시 최소 2GB 필요

• 번들된 EmbeddingGemma 모델 및 런타임 캐싱을 위해 최초 실행 시 아웃바운드 HTTPS 연결 필요

• 호스트 네이티브 개발 시 Go 1.25 이상

• Docker 외부 웹 개발 시 Node 20.15 이상 및 pnpm 10 이상

기본 Docker 경로에는 번들된 EmbeddingGemma Q4 ONNX 제공자를 통한 의미론적 검색이 포함되어 있어 별도의 임베딩 사이드카가 필요하지 않습니다. 최소 및 권장 배포 프로필은 시스템 요구 사항을 참조하세요.

git clone https://github.com/var-gg/pindoc.git
cd pindoc
docker compose up -d --build

Reader 열기:

http://localhost:5830/

새 인스턴스에서는 /가 첫 번째 프로젝트 마법사로 리디렉션됩니다. 마법사를 직접 열려면:

http://localhost:5830/projects/new?welcome=1

MCP 클라이언트 연결

Docker 데몬은 계정 수준의 MCP 엔드포인트 하나를 노출합니다:

{
  "mcpServers": {
    "pindoc": {
      "type": "http",
      "url": "http://127.0.0.1:5830/mcp"
    }
  }
}

프로젝트 범위는 URL에 인코딩되지 않습니다. 에이전트는 프로젝트 범위의 도구 호출 시 project_slug를 전달합니다. pindoc.harness.install로 생성된 워크스페이스는 해당 슬러그를 PINDOC.md 프런트매터에 저장합니다.

일반적인 워크플로우

에이전트에게 프로젝트 맥락을 가지고 작업을 시작하도록 요청하세요:

Use Pindoc context before editing. Find the current project, inspect assigned
Tasks, then implement the next acceptance item.

일반적인 MCP 루프:

1. pindoc.workspace.detect

2. pindoc.task.queue

3. pindoc.context_for_task

4. 코드 또는 문서 작업

5. pindoc.artifact.propose

6. 작업 수락 및 완료 상태 업데이트

구성

기본 Docker 경로는 단일 사용자 및 루프백 전용입니다:

ID 제공자 없이 쓰기 가능한 데몬을 공용 인터넷에 노출하지 마십시오. 읽기 전용 공개 데모의 경우, 리버스 프록시에서 /mcp 및 변경 가능한 HTTP 경로를 차단하십시오. SECURITY.md 및 docs/22-public-demo.md를 참조하세요.

쓰기 가능한 공개 또는 기기 간 인스턴스의 경우 docs/oauth-setup.md를 따르십시오. 여기에는 GitHub OAuth 앱 설정, ${PINDOC_PUBLIC_BASE_URL}/auth/github/callback 콜백 규칙, 런타임 MCP 클라이언트 등록 및 PINDOC_FORCE_OAUTH_LOCAL을 사용한 로컬 OAuth QA가 포함됩니다.

개발

# Run Go tests. Integration tests that need Postgres are skipped unless
# PINDOC_TEST_DATABASE_URL is set.
go test ./...

# Web checks.
cd web
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test:unit
pnpm build

# Full image build.
docker build -t pindoc-server:local .

127.0.0.1을 통해 연결하면서 로컬에서 OAuth Bearer 경로를 테스트하려면 PINDOC_FORCE_OAUTH_LOCAL=true로 설정하십시오. 데몬은 부팅 시 경고를 표시하며 루프백 /mcp 호출에 대해 Bearer 토큰을 요구합니다.

로컬 C 툴체인이 없는 Windows 호스트에서는 Docker를 통해 Go 테스트를 실행하십시오:

docker run --rm -v "${PWD}:/work" -w /work golang:1.25 go test ./...

문서

• 문서 허브

• 공개 데모 계획

• 공개 데모 스토리 경로

• 기록 가치 있는 아티팩트 정책

• 공개 릴리스 체크리스트

• 기여하기

• 보안

• 설계 소스 노트

상태

Pindoc은 현재 활발하게 내부적으로 사용(dogfooding) 중입니다. 로컬 자체 호스팅 경로, Reader UI, 프로젝트/영역 모델, 아티팩트 제안 흐름, 작업 큐, 수정 이력, 요약 및 실제 임베딩 제공자 경로가 구현되었습니다. 공개 OSS 출시 트랙은 초기 실행 안정성, 읽기 전용 데모, CI, 보안 문서 및 더 명확한 협업 포지셔닝에 집중하고 있습니다.

라이선스

Apache License 2.0. LICENSE를 참조하세요.