본문으로 건너뛰기
ai-memory
EnglishPortuguês (Brasil)Españolעברית日本語한국어
메뉴

제품

솔루션

연동

개발자

언어

시작하기GitHub

개발자

ai-memory에 기여하기

지금까지 140명의 코드가 머지되었습니다. 이 페이지는 아이디어에서 출발해 맞는 이슈, 맞는 크레이트, 그리고 첫 리뷰에 통과하는 풀 리퀘스트까지 안내합니다.

참여 방법 고르기CONTRIBUTING.md 읽기

숫자로 보는 활발한 프로젝트

수치는 이 사이트를 빌드할 때 GitHub API에서 가져옵니다.

상위 기여자

GitHub에서 기여자 140명 모두 보기

참여 방법 고르기

각 항목은 GitHub의 해당 페이지로 바로 연결됩니다.

버그 신고

템플릿은 버전, OS, 에이전트, 트랜스포트, 관련 서버 로그를 묻습니다.

버그 리포트 열기

기능 제안

제안은 이슈로 올립니다. 저장소에 discussions 게시판은 없습니다. 템플릿은 어떤 문제를 해결하는지, 기존 설치를 깨뜨리는지를 묻습니다.

기능 요청 열기

첫 이슈 찾기

good first issue 라벨은 처음 참여하는 사람에게 맞는 작업에 붙습니다. 나머지는 help wanted 라벨로 표시합니다.

good first issue 둘러보기

하네스 추가 또는 수정

관리형 하네스 지원에는 문서화된 프로토콜이 있습니다. 네이티브 세션 계약을 증명하고, 저장소는 읽기 전용으로 읽고, 맥락을 전달한 다음에 수신을 확인하고, 필수 테스트를 포함해야 합니다.

하네스 프로토콜 읽기

문서 개선

가이드는 docs/에 markdown으로 있습니다. 문서 수정은 일반 풀 리퀘스트이며, 사용자에게 보이는 변경이 없으면 변경 이력은 건너뜁니다.

docs/ 둘러보기

주변 도구 만들기

임포터, 더 풍부한 UI, 채팅 프런트엔드는 공개 HTTP 및 MCP 인터페이스를 쓰는 컴패니언 프로젝트에 속합니다.

컴패니언 규칙 읽기
다이어그램: 기여는 이슈, 브랜치, 로컬 게이트, 풀 리퀘스트, 리뷰를 거쳐 다음 릴리스에 포함되기까지 여섯 단계를 지납니다.
아이디어에서 릴리스까지. 수정은 다음 패치에, 추가 기능은 다음 마이너에 포함됩니다.

빌드부터 해 보기

빌드는 그 자체로 완결됩니다. 아래 명령 중 환경 변수가 필요한 것은 없습니다.

  1. 클론하고 빌드

    Rust 1.95가 필요하며 rustfmt, clippy와 함께 rust-toolchain.toml에 고정되어 있어서, 첫 빌드 때 rustup이 맞는 툴체인을 설치합니다. SQLite는 번들되어 있고 libgit2는 벤더링되어 있습니다. 표준 C 툴체인 외에는 필요한 것이 없습니다.

    개발 환경 설정
    git clone https://github.com/akitaonrails/ai-memory
cd ai-memory
cargo build --workspace
cargo test --workspace --all-targets

  2. 평소 작업 루프

    cargo t에는 nextest가 필요합니다: cargo install cargo-nextest --locked. 이름이 slow나 stress인 모듈은 건너뛰지만, pre-push 훅과 CI는 이들도 실행합니다.

    작업하는 동안
    cargo t                        # slow 티어를 뺀 전부, 웜 상태에서 약 20초
cargo t -p ai-memory-store     # 크레이트 하나: 그 테스트 바이너리만 빌드
cargo t -E 'test(/purge/)'     # 주제 하나 (전부 빌드하고 일부만 실행)

  3. pre-push 훅 설치

    클론마다 한 번 합니다. .git/hooks/pre-push 안의 자기 블록만 건드립니다. 작업 중인 브랜치에서는 git push --no-verify로 건너뛸 수 있습니다.

    클론마다 한 번
    scripts/install-git-hooks.sh

  4. 푸시 전에 게이트 통과

    CI는 다섯 개를 모두 강제합니다. nextest가 없다면 cargo test --workspace --all-targets가 cargo tf와 같은 역할을 합니다. 마지막 도구가 없다면: cargo install cargo-deny cargo-audit.

    필수 게이트
    cargo fmt --all -- --check
git diff --check
cargo clippy --workspace --all-targets -- -D warnings
cargo tf                            # 모든 테스트 (별칭: cargo nextest run -P full)
cargo deny check                    # 의존성 정책

  5. 커밋에 찍히는 작성자 확인

    GitHub 계정에서 인증된 이메일이나 noreply 주소를 쓰세요. 작성자 정보를 고치려고 main의 히스토리를 다시 쓰는 일은 없습니다.

    커밋 작성자 정보
    git log --format='%h %an <%ae>' "$(git merge-base HEAD origin/main)"..HEAD

기본 규칙과 수용 기준

AGENTS.md는 사람과 코딩 에이전트 모두를 위한 정식 규칙 파일입니다. CONTRIBUTING.md는 이를 아래 내용으로 간추립니다.

작업이 머지되는 방식

  • 변경 이력은 머지 게이트입니다

    사용자에게 보이는 변경은 모두 같은 풀 리퀘스트 안에서 [Unreleased] 아래에 항목을 추가합니다. 리뷰어는 항목 누락을 머지 차단 사유로 봅니다. 리팩터링과 테스트만 바꾸는 변경은 예외입니다.

  • "완료" 전에 테스트

    테스트가 있어야 작업이 완료된 것으로 칩니다. 파서, ID 파생, 보존 계산은 특히 그렇습니다.

  • 죽은 코드도, 반쯤 만든 기능도 없습니다

    스텁은 모듈 주석에 이를 마무리할 마일스톤과 함께 문서화합니다.

  • 변경 범위 안에 머무르세요

    현재 마일스톤에 필요하지 않은 코드는 리팩터링하지 마세요.

  • 주석은 이유를 설명합니다

    바로 윗줄을 되풀이하는 주석은 제거됩니다.

풀 리퀘스트가 깨뜨릴 수 없는 불변식

  • 모든 SQLite 쓰기는 단일 라이터 액터인 WriterHandle을 거칩니다.
  • 설정은 시작할 때 한 번 읽습니다. Config::load 밖에서는 std::env::var를 쓰지 않습니다.
  • 파일 쓰기는 원자적입니다. tmp, rename, fsync 순서이며 제자리 쓰기는 하지 않습니다.
  • 모든 위키 페이지는 (workspace_id, project_id)로 네임스페이스가 나뉩니다.
  • CLI는 얇은 HTTP 클라이언트입니다. SQLite 파일이나 위키 디렉터리를 직접 열지 않습니다.

각 조건이 막아 주는 버그까지 담은 전체 목록은 AGENTS.md에 있습니다

기준이 높게 유지되는 방식

코드 대부분은 AI가 작성합니다. 그 코드는 전부 사람이 읽으며, 신뢰만으로 머지되는 코드는 없습니다. 아래 규칙은 모두 실제로 문제가 생긴 뒤에 만들어졌습니다.

다이어그램: 네 단계로 이루어진 루프. 실수가 문서화된 규칙이 되고, 그 규칙을 깨뜨리려는 테스트가 만들어지며, 그 테스트는 모든 풀 리퀘스트의 게이트로 실행됩니다. 중앙에는 사람이 있어 결정을 내립니다.
이 중 어느 것도 처음부터 있었던 것은 아닙니다. 각 규칙은 실제 오류가 발생한 뒤에 추가되었고, 모든 풀 리퀘스트에서 검사됩니다.

  • 규칙은 오류에서 나옵니다

    각 불변식에는 원인이 된 버그와 이를 막는 코드가 함께 적혀 있습니다. 실패 사례로 거슬러 올라갈 수 없는 규칙은 삭제됩니다.

  • 모든 풀 리퀘스트는 감사를 거칩니다

    풀 리퀘스트의 주장은 코드와 대조해 확인하고, 게이트를 다시 실행하며, 검증된 것만 머지됩니다. 감사 체크리스트는 공개되어 있습니다.

  • 사람이 결정합니다

    타이핑 대부분은 AI가 합니다. 메인테이너가 읽고, 고치고, 잘못된 부분을 다음 규칙으로 만듭니다.

감사 체크리스트 읽기

모델 두 개, 감사 체크리스트 하나

ai-jail을 대상으로 한 작은 실험입니다. ai-jail은 --yolo로 실행한 에이전트를 맡길 수 있는 샌드박스입니다. 같은 커밋에 같은 security-audit 체크리스트를 두 모델이 각각 돌리고, 그 결과를 비교했습니다.

  • 대상

    ai-jail은 코딩 에이전트를 OS 샌드박스 안에서 실행합니다. Linux에서는 bubblewrap과 Landlock, seccomp를, macOS에서는 sandbox-exec를 사용합니다. 코드가 위험할 때 폐기 가능한 머신을 대신할 수는 없는, 하나의 보호 계층일 뿐입니다.

    aijail.io

  • 첫 번째 실행

    OpenCode로 구동되는 Genesys Pi가 먼저 ai-jail에서 일반적인 구현 작업을 하고 머지했습니다. 그런 다음 공개 skills 저장소에 있는 security-audit skill을 v2.3.0에 대해 실행했습니다.

    skills를 소개한 글

  • 두 번째 실행

    Claude Fable 5.1은 첫 번째 보고서를 읽지 않은 채 같은 커밋에 같은 skill을 실행했습니다. 목록을 확정한 뒤에는 두 보고서에 공통으로 나온 단서를 모두 소스 코드에서 다시 검증하며 비교 결과를 작성했습니다.

  1. 둘 다 발견11
  2. Genesys Pi만 발견11
  3. Claude Fable 5.1만 발견3
심각도는 각 보고서에 적힌 그대로입니다. 두 보고서 모두 같은 높음(High) 등급 발견 사항 두 건을 각자 재현했습니다.

  • 동일한 높음(High) 두 건

    위조된 워크트리 메타데이터로 호스트 디렉터리에 대한 읽기/쓰기 권한을 얻을 수 있었고, 중복된 환경 변수 항목이 가짜 자격 증명(phantom secret)을 우회했습니다. 두 모델은 서로의 결과를 보지 않고도 두 가지 모두 재현했습니다.

  • Genesys Pi는 더 넓게 봤습니다

    Genesys Pi만 찾아낸 발견 사항이 11건 있었습니다. macOS 전체 영역과 프록시의 리소스 제한이 포함되어 있었고, 심각도 판단도 더 정확했습니다. Fable은 실제 버그 하나를 오탐으로 처리했고, 다른 두 건은 교차 검증 전까지 미해결 상태로 남겨두었습니다.

  • Fable이 가장 날카로운 발견을 했습니다

    릴리스 바이너리에 남아 있던 테스트 전용 우회 스위치 두 개는 환경 변수에서 값을 읽어들였고, 가짜 자격 증명이 보호하는 바로 그 경로에 있었습니다. 다른 보고서가 익스플로잇을 추론으로만 다룬 부분에서 Fable은 실제로 실행까지 했습니다.

ai-jail 저장소에 있는 세 보고서

코드베이스 지도

바이너리에는 크레이트 열 개가 들어갑니다. 크레이트마다 책임은 하나이고 타입이 있는 API를 가지며, 순환 의존성은 없습니다.

다이어그램: 네 개 층으로 나뉜 크레이트. 맨 위에 cli 크레이트가 있습니다. 그 아래에 hooks, mcp, web, consolidate, workstream이 있습니다. 그 아래에 store, wiki, llm이 있습니다. core 크레이트는 모든 것의 기반입니다.
ai-memory- 접두사를 뺀 크레이트 이름입니다. 모든 크레이트가 core에 의존하고, cli 크레이트만 나머지 전부에 의존합니다.
크레이트들어 있는 것
ai-memory-core도메인 타입, 에러, id. IO 없음.
ai-memory-storeSQLite, 라이터 액터, 리더 풀, 감쇠 계산.
ai-memory-wiki원자적 markdown 쓰기, 파일 워처, git.
ai-memory-mcpMCP 트랜스포트, 도구 라우터, 관리자 라우트.
ai-memory-hooks훅 페이로드 스키마, 새니타이저, /hook 엔드포인트.
ai-memory-llm제공자 인증 경계, LLM 및 임베더 트레이트.
ai-memory-consolidate수집, 린트, 스윕, 자동 개선 파이프라인.
ai-memory-web읽기 전용 /web 브라우저와 /api/v1 JSON 라우트.
ai-memory-workstream읽기 전용 네이티브 트랜스크립트 리더와 ai-memory run 뒤의 실행 어댑터.
ai-memory-cliai-memory 바이너리와 얇은 HTTP 서브커맨드.

crates/ 바깥

디렉터리들어 있는 것
companions/ai-memory-importer. 루트 워크스페이스 밖에 있는 독립 패키지입니다. --manifest-path로 빌드합니다.
hooks/라이프사이클 훅 번들. 에이전트마다 폴더 하나, 셸과 네이티브.
evals/벤치마크 하네스. 워크스페이스 멤버이지만 배포되지 않습니다.
docs/아키텍처, 설계 결정, 설치, 배포, 사용 가이드.
tests/엔드투엔드 스모크 테스트, 훅 셸 테스트, 픽스처.

통합 테스트는 각 크레이트 안의 tests/suite/에 있습니다. 크레이트 간에 공유하는 헬퍼는 crates/ai-memory-test-support에 두며, 이 크레이트는 배포되지 않습니다.

풀 리퀘스트 리뷰 방식

리뷰는 풀 리퀘스트 템플릿을 따라 진행되므로, 템플릿을 정직하게 채우는 것이 일의 대부분입니다.

  • 템플릿이 곧 체크리스트입니다

    무엇이 왜 바뀌었는지, 게이트를 체크한 테스트 계획, 커밋 작성자 정보, 릴리스 영향, 변경 이력 항목을 묻습니다.

  • 어떤 종류의 릴리스인지 밝히세요

    패치, 마이너, 메이저 중 하나를 체크합니다. 수정을 "Added" 아래에 넣으면 엉뚱한 버전이 올라갈 수 있으니, 변경 이력 항목은 맞는 제목 아래에 두세요.

  • 호환성을 깨는 변경은 메이저를 기다립니다

    설명에 분명히 적어 주세요. breaking-change 라벨이 붙고 일정이 따로 잡히므로, 패치와 마이너 릴리스를 막지 않습니다.

  • 머지마다 도는 CI는 빠릅니다

    머지는 빠른 Linux 잡만 통과하면 됩니다. macOS와 Windows 잡은 라벨을 붙이거나, 매일 밤, 또는 수동으로 실행되며, 릴리스 전에는 항상 실행됩니다.

  • 수정이 먼저 나갑니다

    버그 수정은 다음 패치 릴리스에 나가며 기능 작업 때문에 미뤄지지 않습니다. 새 하네스나 제공자는 다음 마이너에 포함됩니다.

하네스 풀 리퀘스트는 이 짧은 게이트를 실행하고, 테스트한 CLI 버전을 기록하며, 실제 하네스를 대상으로 한 수동 확인을 포함합니다.

managed-harness-contributions.md에서
cargo fmt --check
git diff --check
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

이어서 읽기

바꾸기 전에 먼저 써 보세요.

하루 동안 자기 프로젝트에 돌려 보세요. 거기서 찾은 버그가 첫 이슈가 됩니다.

지금 설치하기GitHub에서 스타 주기