מפתחים
תורמים ל-ai-memory
עד עכשיו 140 אנשים הכניסו קוד. הדף הזה לוקח אתכם מרעיון אל ה-issue הנכון, אל ה-crate הנכון ואל pull request שעובר review בפעם הראשונה.
פרויקט פעיל, במספרים
הספירות מגיעות מה-API של GitHub בזמן שהאתר נבנה.
התורמים המובילים
akitaonrails
djalmajr
viniciusdsandrade
everton-dgn
samirhvbr
lucasliet
felipe-NR
wblech
kevin9327
rthiago
maxeinstein-dev
matheus-rodrigues00
luisfnicolau
petersonsalme
rubenlr
talyssonoc
rafaelkenedy
evanmaranzano
JohnC0de
pablowinck
gabrielscharb
lhzapata
abhisheksharma2411
aguirreSL
caminhar-deus
gb
rntjr
mrpaiva
rodrigopalhares
yubr-zzh
lihuiyang1024
GrYllO
giovannirco
pvpmartins
atirna
Murillofilho86
mobnix
vitorvilas
zanlucathiago
Cardosaum
alvadorn
victorcesc
pedrofjr
enrell
davividal
Barba2k2
alanhoff
ArtroxGabriel
seathatflowsinourveins
milesibastos
klebervirgilio
iagogfe
dk96-creator
juniorgaudencio00-code
BobDylans
bcosta19
Gaalbu
cateim
בחירת דרך כניסה
כל אחת מהן מובילה בדיוק לדף הנכון ב-GitHub.
מדווחים על באג
התבנית מבקשת את הגרסה, מערכת ההפעלה, הסוכן, ה-transport ושורות הלוג הרלוונטיות של השרת.
פתיחת דיווח על באגמציעים פיצ'ר
הצעות הן issues, כי ל-repository אין לוח discussions. התבנית שואלת איזו בעיה זה פותר ואם זה ישבור התקנות קיימות.
פתיחת בקשה לפיצ'רמוצאים issue ראשון
התווית good first issue מסמנת עבודה שמתאימה למי שחדש בפרויקט. help wanted מסמנת את השאר.
ל-good first issuesמוסיפים או מתקנים harness
לתמיכה ב-harness מנוהל יש פרוטוקול כתוב: מוכיחים את חוזה הסשן הנייטיב, קוראים מאגרים לקריאה בלבד, מעבירים הקשר לפני שמאשרים אותו, ומצרפים את הטסטים הנדרשים.
לפרוטוקול ה-harnessמשפרים את התיעוד
המדריכים יושבים ב-docs/ כ-markdown. תיקון תיעוד הוא pull request רגיל, והוא מדלג על יומן השינויים כששום דבר שגלוי למשתמש לא משתנה.
לתיקיית docs/בונים מסביב
importers, ממשקי משתמש עשירים יותר וממשקי צ'אט שייכים לפרויקטים נלווים (companion) שמשתמשים בממשקי ה-HTTP וה-MCP הציבוריים.
לכללי ה-companion
מגיעים ל-build שעובד
ה-build עומד בפני עצמו. אף אחת מהפקודות האלה לא צריכה משתנה סביבה.
עושים clone ו-build
נדרש Rust 1.95, והוא מקובע ב-
rust-toolchain.tomlיחד עם rustfmt ו-clippy, כך ש-rustup מתקין את ה-toolchain הנכון ב-build הראשון. SQLite מגיע ארוז בפנים ו-libgit2 הוא vendored. צריך toolchain סטנדרטי של 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 hook וה-CI עדיין מריצים.תוך כדי עבודה cargo t # הכול חוץ מהשכבה האיטית, כ-20 שניות כשה-cache חם cargo t -p ai-memory-store # crate אחד: בונה רק את קובצי הטסט שלו cargo t -E 'test(/purge/)' # נושא אחד (בונה הכול, מריץ תת-קבוצה)מתקינים את ה-pre-push hook
פעם אחת לכל clone. הוא נוגע רק בבלוק של עצמו בתוך
.git/hooks/pre-push. ב-branch של עבודה בתהליך,git push --no-verifyמדלג עליו.פעם אחת לכל clone scripts/install-git-hooks.shעוברים את בדיקות החובה לפני push
ה-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 # כל הטסטים (alias: cargo nextest run -P full) cargo deny check # מדיניות תלויותבודקים על שם מי ה-commits שלכם רשומים
משתמשים באימייל שאומת בחשבון ה-GitHub שלכם, או בכתובת ה-noreply שלו. ההיסטוריה ב-main אף פעם לא נכתבת מחדש כדי לתקן ייחוס.
ייחוס של commits git log --format='%h %an <%ae>' "$(git merge-base HEAD origin/main)"..HEAD
כללי היסוד ורף הקבלה
AGENTS.md הוא קובץ הכללים הקנוני, לאנשים ולסוכני קוד. CONTRIBUTING.md מתמצת אותו לזה.
איך עבודה אמורה להיכנס
יומן השינויים הוא תנאי ל-merge
כל שינוי שגלוי למשתמש מוסיף רשומה תחת [Unreleased] באותו pull request. רשומה חסרה חוסמת את ה-review. refactors ושינויים בטסטים בלבד פטורים.
טסטים לפני "גמור"
עבודה נחשבת גמורה כשיש לה טסטים, ובראש ובראשונה parsers, גזירת מזהים וחישובי ה-retention.
בלי קוד מת, בלי פיצ'רים חצי בנויים
stubs מתועדים בהערת המודול, יחד עם אבן הדרך שתשלים אותם.
נשארים בתוך גבולות השינוי
לא עושים refactor לקוד שאבן הדרך הנוכחית לא צריכה.
הערות מסבירות למה
הערה שחוזרת על השורה שמעליה נמחקת.
אינווריאנטים ש-pull request לא יכול לשבור
- כל הכתיבות ל-SQLite עוברות דרך ה-writer actor היחיד,
WriterHandle. - הקונפיגורציה נקראת פעם אחת בעלייה. אין
std::env::varמחוץ ל-Config::load. - כתיבות לקבצים הן אטומיות: tmp, rename, fsync. אף פעם לא במקום.
- כל דף ויקי משויך ל-namespace של
(workspace_id, project_id). - ה-CLI הוא לקוח HTTP דק. הוא אף פעם לא פותח את קובץ ה-SQLite או את תיקיית הוויקי.
איך הרף נשאר גבוה
AI כותב את רוב הקוד. אדם קורא את כולו, ושום קוד לא עובר merge על סמך אמון בלבד. כל כלל שמופיע כאן קיים כי משהו השתבש פעם אחת.
- 73כללים כתובים ב-AGENTS.md
- 16אינווריאנטים ש-pull request לא יכול לשבור
- 92מסמכים: מחקר, post-mortems, החלטות
- 5,208טסטים, unit ואינטגרציה
כללים מגיעים מטעויות
כל אינווריאנט מפרט את הבאג שגרם לו ואת הקוד שמונע אותו. כלל שאי אפשר לשייך לתקלה מוסר.
כל pull request עובר ביקורת
הטענות ב-pull request נבדקות מול הקוד, בדיקות החובה רצות שוב, ורק מה שאומת עובר merge. ה-checklists של הביקורת פומביים.
אדם מחליט
ה-AI עושה את רוב ההקלדה. המתחזק קורא, מתקן, והופך את מה שהשתבש לכלל הבא.
שני מודלים, checklist אחד לביקורת
ניסוי קטן ב-ai-jail, ה-sandbox שאפשר למסור אליו הרצת --yolo. אותו checklist של security-audit הורץ על ידי שני מודלים, על אותו commit, ואז הושווה.
היעד
ai-jail מריץ סוכן קוד בתוך sandbox של מערכת ההפעלה: bubblewrap עם Landlock ו-seccomp ב-Linux, sandbox-exec ב-macOS. זו שכבת הגנה, לא תחליף למכונה חד-פעמית כשהקוד עוין.
aijail.ioהריצה הראשונה
Genesys Pi, שהופעל דרך OpenCode, קודם ביצע עבודת פיתוח רגילה על ai-jail ומיזג אותה. אחר כך הוא הריץ את ה-checklist של security-audit ממאגר ה-skills הציבורי מול v2.3.0.
הפוסט על ה-skillsהריצה השנייה
Claude Fable 5.1 הריץ את אותו checklist על אותו commit, בלי לקרוא את הדוח הראשון. לאחר שרשימתו ננעלה, הוא גזר מחדש מהמקור כל ממצא משותף וכתב את ההשוואה.
- נמצא על ידי שניהם11
- רק Genesys Pi11
- רק Claude Fable 5.13
אותם שני ממצאי High
מטא-דאטה מזויף של worktree העניק הרשאות קריאה וכתיבה על תיקיית host, וערכי environment כפולים עקפו את ה-phantom secret. כל אחד מהמודלים שחזר את שניהם בעצמו, בלי תלות באחר.
Genesys Pi כיסה יותר שטח
אחד עשר ממצאים שרק הוא הגיע אליהם, וביניהם כל משטח ה-macOS ומגבלות המשאבים של ה-proxy, עם קביעות חומרה מדויקות יותר. Fable דחה באג אמיתי אחד והשאיר שניים נוספים לא פתורים עד ההצלבה בין הדוחות.
Fable איתר את הפספוס החד ביותר
שני escape hatches שנועדו לטסטים בלבד בתוך ה-binary של ה-release, נקראים מה-environment וממוקמים בדיוק על הנתיב שה-phantom credentials אמורים להגן עליו. הוא גם הריץ בפועל את ה-exploits, במקום שבו הדוח השני רק נימק לגביהם.
מפה של בסיס הקוד
עשרה crates נכנסים לקובץ הבינארי. לכל אחד יש אחריות אחת ו-API מטופס, ואין תלויות מעגליות.
| Crate | מה יושב שם |
|---|---|
ai-memory-core | טיפוסי הדומיין, שגיאות ומזהים. בלי IO. |
ai-memory-store | SQLite, ה-writer actor, מאגר הקוראים וחישובי הדעיכה. |
ai-memory-wiki | כתיבות markdown אטומיות, ה-file watcher ו-git. |
ai-memory-mcp | ה-transport של MCP, נתב הכלים ונתיבי הניהול. |
ai-memory-hooks | סכמות ה-payload של ה-hooks, ה-sanitizer וה-endpoint של /hook. |
ai-memory-llm | גבול האימות מול הספקים וה-traits של ה-LLM ושל ה-embedder. |
ai-memory-consolidate | הזנה, lint, sweep וה-pipeline של auto-improve. |
ai-memory-web | הדפדפן לקריאה בלבד ב-/web ונתיבי ה-JSON של /api/v1. |
ai-memory-workstream | קוראים לקריאה בלבד של תמלילים נייטיב, ומתאמי ההפעלה שמאחורי ai-memory run. |
ai-memory-cli | הקובץ הבינארי ai-memory ותת-הפקודות הדקות שלו מעל HTTP. |
מחוץ ל-crates/
| תיקייה | מה יושב שם |
|---|---|
companions/ | ai-memory-importer, חבילה עצמאית מחוץ ל-workspace הראשי. בונים אותה עם --manifest-path. |
hooks/ | חבילות hooks של מחזור החיים, תיקייה לכל סוכן, ב-shell ונייטיב. |
evals/ | ה-harness של הבנצ'מרק. חבר ב-workspace שאף פעם לא משוחרר. |
docs/ | ארכיטקטורה, החלטות תכנון, ומדריכי התקנה, פריסה ושימוש. |
tests/ | טסטי smoke מקצה לקצה, טסטי shell של ה-hooks ו-fixtures. |
טסטי האינטגרציה יושבים ב-tests/suite/ בתוך כל crate. עזרים שמשותפים לכמה crates נכנסים ל-crates/ai-memory-test-support, שאף פעם לא משוחרר.
איך עושים review ל-pull requests
ה-review הולך לפי תבנית ה-pull request, אז מילוי כן שלה הוא רוב העבודה.
התבנית היא ה-checklist
היא שואלת מה השתנה, למה, מה תוכנית הבדיקות עם בדיקות החובה מסומנות, ייחוס ה-commits, ההשפעה על הגרסה ורשומת יומן השינויים.
אומרים איזה סוג גרסה זה
מסמנים patch, minor או major. תיקון שנרשם תחת "Added" עלול להקפיץ את הגרסה הלא נכונה, אז שמים את הרשומה ביומן השינויים תחת הכותרת הנכונה.
שינויים שוברים מחכים ל-major
מציינים אותם בתיאור. הם מקבלים את התווית breaking-change ומתוזמנים, כך שהם לא מעכבים גרסאות patch ו-minor.
ה-CI מהיר בכל merge
merge מותנה ב-jobs המהירים של Linux. ה-jobs של macOS ושל Windows רצים לפי תווית, מדי לילה או ידנית, ותמיד לפני גרסה.
תיקונים יוצאים ראשונים
תיקון באג יוצא בגרסת ה-patch הבאה ולא מחכה לעבודה על פיצ'רים. harness חדש או ספק חדש יוצאים ב-minor הבא.
pull request של harness מריץ את הבדיקה המקוצרת הזאת, רושם מול איזו גרסת CLI הוא נבדק, וכולל מעבר ידני מול ה-harness האמיתי.
cargo fmt --check
git diff --check
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
נסו אותו לפני שמשנים אותו.
מריצים אותו יום אחד על הפרויקטים שלכם. הבאג שתמצאו הוא ה-issue הראשון שלכם.