개발자
ai-memory에 기여하기
지금까지 101명의 코드가 머지되었습니다. 이 페이지는 아이디어에서 출발해 맞는 이슈, 맞는 크레이트, 그리고 첫 리뷰에 통과하는 풀 리퀘스트까지 안내합니다.
숫자로 보는 활발한 프로젝트
수치는 이 사이트를 빌드할 때 GitHub API에서 가져옵니다.
상위 기여자
akitaonrails
djalmajr
samirhvbr
lucasliet
wblech
rthiago
matheus-rodrigues00
lhzapata
gabrielscharb
pablowinck
aguirreSL
evanmaranzano
kevin9327
gb
mrpaiva
rafaelkenedy
lihuiyang1024
rodrigopalhares
felipe-NR
abhisheksharma2411
Cardosaum
vitorvilas
mobnix
Murillofilho86
viniciusdsandrade
atirna
pedrofjr
enrell
zanlucathiago
davividal
alanhoff
alvadorn
milesibastos
klebervirgilio
iagogfe
dk96-creator
juniorgaudencio00-code
PedroPCardoso
marcelomogami
lucazz
jpramos123
cateim
Gaalbu
bcosta19
BobDylans
victorcesc
Wprosdocimo
XiaoHuo888-hue
adrianogomes-NE
azevedo-luis
cristianodewes
luisfnicolau
omartelo
wslcb
holocaster
rpaggi
murilojrpereiras
LuizFernando991
jaysonsantos
참여 방법 고르기
각 항목은 GitHub의 해당 페이지로 바로 연결됩니다.
버그 신고
템플릿은 버전, OS, 에이전트, 트랜스포트, 관련 서버 로그를 묻습니다.
버그 리포트 열기기능 제안
제안은 이슈로 올립니다. 저장소에 discussions 게시판은 없습니다. 템플릿은 어떤 문제를 해결하는지, 기존 설치를 깨뜨리는지를 묻습니다.
기능 요청 열기첫 이슈 찾기
good first issue 라벨은 처음 참여하는 사람에게 맞는 작업에 붙습니다. 나머지는 help wanted 라벨로 표시합니다.
good first issue 둘러보기하네스 추가 또는 수정
관리형 하네스 지원에는 문서화된 프로토콜이 있습니다. 네이티브 세션 계약을 증명하고, 저장소는 읽기 전용으로 읽고, 맥락을 전달한 다음에 수신을 확인하고, 필수 테스트를 포함해야 합니다.
하네스 프로토콜 읽기문서 개선
가이드는 docs/에 markdown으로 있습니다. 문서 수정은 일반 풀 리퀘스트이며, 사용자에게 보이는 변경이 없으면 변경 이력은 건너뜁니다.
docs/ 둘러보기주변 도구 만들기
임포터, 더 풍부한 UI, 채팅 프런트엔드는 공개 HTTP 및 MCP 인터페이스를 쓰는 컴패니언 프로젝트에 속합니다.
컴패니언 규칙 읽기
빌드부터 해 보기
빌드는 그 자체로 완결됩니다. 아래 명령 중 환경 변수가 필요한 것은 없습니다.
클론하고 빌드
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평소 작업 루프
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/)' # 주제 하나 (전부 빌드하고 일부만 실행)pre-push 훅 설치
클론마다 한 번 합니다.
.git/hooks/pre-push안의 자기 블록만 건드립니다. 작업 중인 브랜치에서는git push --no-verify로 건너뛸 수 있습니다.클론마다 한 번 scripts/install-git-hooks.sh푸시 전에 게이트 통과
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 # 의존성 정책커밋에 찍히는 작성자 확인
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 파일이나 위키 디렉터리를 직접 열지 않습니다.
코드베이스 지도
바이너리에는 크레이트 열 개가 들어갑니다. 크레이트마다 책임은 하나이고 타입이 있는 API를 가지며, 순환 의존성은 없습니다.
| 크레이트 | 들어 있는 것 |
|---|---|
ai-memory-core | 도메인 타입, 에러, id. IO 없음. |
ai-memory-store | SQLite, 라이터 액터, 리더 풀, 감쇠 계산. |
ai-memory-wiki | 원자적 markdown 쓰기, 파일 워처, git. |
ai-memory-mcp | MCP 트랜스포트, 도구 라우터, 관리자 라우트. |
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-cli | ai-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 버전을 기록하며, 실제 하네스를 대상으로 한 수동 확인을 포함합니다.
cargo fmt --check
git diff --check
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings