An active project, in numbers

Counts come from the GitHub API when this site is built.

Top contributors

See all 140 contributors on GitHub

Pick your way in

Each of these goes to the exact page on GitHub.

Report a bug

The template asks for your version, OS, agent, transport and the relevant server log lines.

Open a bug report

Propose a feature

Proposals are issues; the repository has no discussions board. The template asks what problem it solves and whether it would break existing installs.

Open a feature request

Find a first issue

The good first issue label marks work that suits a newcomer. Help wanted marks the rest.

Browse good first issues

Add or fix a harness

Managed harness support has a written protocol: prove the native session contract, read stores read-only, deliver context before acknowledging it, and ship the required tests.

Read the harness protocol

Improve the docs

Guides live in docs/ as markdown. A doc fix is a normal pull request and skips the changelog when nothing user-facing changes.

Browse docs/

Build around it

Importers, richer UIs and chat front ends belong in companion projects that use the public HTTP and MCP surfaces.

Read the companion rules

Diagram: a contribution moves through six stages, from an issue, to a branch, to the local gates, to a pull request, to review, and ships in the next release. — From idea to release. Fixes ship in the next patch, additive features in the next minor.

Get it building

The build is self-contained. None of these commands needs an environment variable.

1
Clone and build
Rust 1.95 is required and pinned in rust-toolchain.toml, with rustfmt and clippy, so rustup installs the right toolchain on first build. SQLite is bundled and libgit2 is vendored. You need a standard C toolchain and nothing else.
dev setup
```
git clone https://github.com/akitaonrails/ai-memory
cd ai-memory
cargo build --workspace
cargo test --workspace --all-targets
```

Use the everyday loop

cargo t needs nextest: cargo install cargo-nextest --locked. It skips modules named slow or stress, which the pre-push hook and CI still run.

while you work

cargo t                        # all but the slow tier, ~20s warm
cargo t -p ai-memory-store     # one crate: builds only its test binaries
cargo t -E 'test(/purge/)'     # one topic (builds everything, runs a subset)

3
Install the pre-push hook
Once per clone. It only touches its own block in .git/hooks/pre-push. On a work-in-progress branch, git push --no-verify skips it.
once per clone
```
scripts/install-git-hooks.sh
```

Pass the gates before you push

CI enforces all five. Without nextest, cargo test --workspace --all-targets is the equivalent of cargo tf. If the last one is missing: cargo install cargo-deny cargo-audit.

required gates

cargo fmt --all -- --check
git diff --check
cargo clippy --workspace --all-targets -- -D warnings
cargo tf                            # every test (alias: cargo nextest run -P full)
cargo deny check                    # dependency policy

5
Check who your commits say you are
Use an email verified on your GitHub account or its noreply address. History on main is never rewritten to fix attribution.
commit attribution
```
git log --format='%h %an <%ae>' "$(git merge-base HEAD origin/main)"..HEAD
```

Ground rules and the acceptance bar

AGENTS.md is the canonical rules file for people and for coding agents. CONTRIBUTING.md condenses it to this.

How work is expected to land

The changelog is a merge gate
Every user-facing change adds an entry under [Unreleased] in the same pull request. Reviewers treat a missing entry as blocking. Refactors and test-only changes are exempt.
Tests before “done”
Work counts as done once it has tests, above all parsers, ID derivation and the retention math.
No dead code, no half-built features
Stubs are documented in the module comment with the milestone that will finish them.
Stay inside the change
Do not refactor code the current milestone does not need.
Comments explain why
A comment that restates the line above it gets removed.

Invariants a pull request cannot break

All SQLite writes go through the single writer actor, WriterHandle.
Config is read once at startup. No std::env::var outside Config::load.
File writes are atomic: tmp, rename, fsync. Never in place.
Every wiki page is namespaced by (workspace_id, project_id).
The CLI is a thin HTTP client. It never opens the SQLite file or the wiki directory.

The full list, with the bug each one prevents, is in AGENTS.md

How the bar stays high

AI writes most of the code. A person reads all of it, and nothing merges on trust. Every rule below exists because something went wrong once.

Diagram: a loop with four stages. A mistake becomes a written rule, the rule gets a test that tries to break it, and the test runs as a gate on every pull request. A person sits at the center and decides. — None of this existed on day one. Each rule was added after a real error, and each one is checked on every pull request.

Rules come from errors
Each invariant names the bug that caused it and the code that prevents it. A rule nobody can trace to a failure gets removed.
Every pull request is audited
The claims in a pull request are checked against the code, the gates run again, and only what was verified merges. The audit checklists are public.
A person decides
The AI does most of the typing. The maintainer reads, corrects, and turns what went wrong into the next rule.

Read the audit checklists

Two models, one audit checklist

A small experiment on ai-jail, the sandbox a --yolo run can be handed to. The same security-audit checklist, run by two models on the same commit, then compared.

The target
ai-jail runs a coding agent inside an OS sandbox: bubblewrap with Landlock and seccomp on Linux, sandbox-exec on macOS. It is a layer, not a substitute for a disposable machine when the code is hostile.
aijail.io
The first run
Genesys Pi, driven through OpenCode, first did ordinary implementation work on ai-jail and landed it. Then it ran the security-audit skill from the public skills repository against v2.3.0.
The post about the skills
The second run
Claude Fable 5.1 ran the same skill on the same commit without reading the first report. Once its list was fixed, it re-derived every shared lead from source and wrote the comparison.

Found by both11
Only Genesys Pi11
Only Claude Fable 5.13

All severities as each report stated them. Both reports reproduced the same two High findings on their own.

Same two Highs
Forged worktree metadata gave read and write on a host directory, and duplicate environment entries slipped past the phantom secret. Each model reproduced both without the other.
Genesys Pi went wider
Eleven findings only it reached, among them the whole macOS surface and the proxy’s resource limits, with sharper severity calls. Fable had rejected one real bug and left two others unresolved until the cross-check.
Fable found the sharpest miss
Two test-only escape hatches in the release binary, read from the environment, sat on the exact path the phantom credentials protect. It also ran the exploits where the other report reasoned about them.

The three reports, in the ai-jail repository

A map of the codebase

Ten crates ship in the binary. Each has one responsibility and a typed API, and there are no circular dependencies.

Diagram: the crates in four tiers. The cli crate is on top. Below it are hooks, mcp, web, consolidate and workstream. Below those are store, wiki and llm. The core crate is the foundation under everything. — Crate names without the ai-memory- prefix. Everything depends on core, and only the cli crate depends on everything.

Crate	What lives there
`ai-memory-core`	Domain types, errors and ids. No IO.
`ai-memory-store`	SQLite, the writer actor, the reader pool and the decay math.
`ai-memory-wiki`	Atomic markdown writes, the file watcher and git.
`ai-memory-mcp`	The MCP transport, the tool router and the admin routes.
`ai-memory-hooks`	Hook payload schemas, the sanitizer and the /hook endpoint.
`ai-memory-llm`	The provider auth boundary and the LLM and embedder traits.
`ai-memory-consolidate`	Ingest, lint, sweep and the auto-improve pipeline.
`ai-memory-web`	The read-only /web browser and the /api/v1 JSON routes.
`ai-memory-workstream`	Read-only native transcript readers and the launch adapters behind ai-memory run.
`ai-memory-cli`	The ai-memory binary and its thin HTTP subcommands.

Outside crates/

Directory	What lives there
`companions/`	ai-memory-importer, a standalone package outside the root workspace. Build it with --manifest-path.
`hooks/`	Lifecycle hook bundles, one folder per agent, shell and native.
`evals/`	The benchmark harness. A workspace member that is never shipped.
`docs/`	Architecture, design decisions, install, deploy and usage guides.
`tests/`	End-to-end smoke tests, hook shell tests and fixtures.

Integration tests live in tests/suite/ inside each crate. Helpers shared between crates go in crates/ai-memory-test-support, which is never shipped.

How pull requests get reviewed

Reviews follow the pull request template, so filling it in honestly is most of the work.

The template is the checklist
It asks what changed, why, a test plan with the gates ticked, commit attribution, release impact and the changelog entry.
Say what kind of release it is
Tick patch, minor or major. A fix filed under “Added” can bump the wrong version, so put the changelog entry under the right heading.
Breaking changes wait for a major
Call them out in the description. They get the breaking-change label and are scheduled, so they do not hold up patch and minor releases.
CI is fast per merge
A merge gates on the fast Linux jobs. The macOS and Windows legs run on a label, nightly or by hand, and always before a release.
Fixes ship first
A bug fix goes out in the next patch release and is not held for feature work. A new harness or provider ships in the next minor.

A harness pull request runs this shorter gate, records the CLI version it was tested against, and includes a manual pass against the real harness.

from managed-harness-contributions.md

cargo fmt --check
git diff --check
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

Try it before you change it.

Run it on your own projects for a day. The bug you find is your first issue.

Install now Star it on GitHub

An active project, in numbers

Top contributors

Pick your way in

Report a bug

Propose a feature

Find a first issue

Add or fix a harness

Improve the docs

Build around it

Get it building

Clone and build

Use the everyday loop

Install the pre-push hook

Pass the gates before you push

Check who your commits say you are

Ground rules and the acceptance bar

How work is expected to land

Invariants a pull request cannot break

How the bar stays high

Rules come from errors

Every pull request is audited

A person decides

Two models, one audit checklist

The target

The first run

The second run

Same two Highs

Genesys Pi went wider

Fable found the sharpest miss

A map of the codebase

Outside crates/

How pull requests get reviewed

The template is the checklist

Say what kind of release it is

Breaking changes wait for a major

CI is fast per merge

Fixes ship first

Keep reading

Architecture

Research and rationale

Agents and editors

Try it before you change it.