ai-memory Engineering Standards

Authoritative reference for all development, testing, security, and release processes. Maintained by AlphaOne LLC. All contributors and AI agents must follow these standards. In case of conflict with CONTRIBUTING.md, this document takes precedence.

AI agents must additionally follow AI_DEVELOPER_WORKFLOW.md (operational steps) and AI_DEVELOPER_GOVERNANCE.md (policy boundaries). The Governance standard takes precedence over this document only on matters of AI participation; this document remains authoritative for code, test, security, and release.

1. Development Standards

1.1 Repository

There is no separate development repo. ai-memory-mcp-dev is archived.

1.2 Branch Strategy

• main — production releases, protected branch, requires owner approval
• develop — active development, all PRs target this branch
• Feature/fix branches created from develop (e.g., feature/batch-import, fix/ttl-overflow)
• Maintainers merge develop into main when cutting a release

1.3 Branch Protection (main)

No code reaches main without the project owner’s explicit approval.

PRs to develop do not require owner approval but must pass all CI checks (fmt, clippy pedantic, tests).

1.4 Code Style

• Rust 1.87+ minimum supported version (MSRV). Required for is_multiple_of() stabilization.
• cargo fmt is mandatory. CI enforces via cargo fmt --check. Always run before committing.
• cargo clippy with pedantic:

  cargo clippy -- -D warnings -D clippy::all -D clippy::pedantic
  

  Zero warnings. If a pedantic lint requires #[allow(clippy::...)], it must be justified in the PR description.

• SPDX headers required on all source files. Use the year of file creation:

  // Copyright <YEAR> AlphaOne LLC
  // SPDX-License-Identifier: Apache-2.0
  

• No new production unwrap() calls. Use ?, .map_err(), unwrap_or_default(), or match expressions.
• All SQL queries must use parameterized queries (params![]). No string interpolation in SQL.
• FTS5 input sanitized via sanitize_fts_query().

1.5 Commit Messages

Format:

<type>: <short summary>

<optional body explaining the change in more detail>

Types: feat, fix, docs, style, refactor, test, chore, perf.

• Reference issues: Closes #52
• AI-generated commits include: Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

1.6 PR Requirements

Every PR must pass these gates before merge:

Contributors are responsible for the first six gates (four cargo + two script gates wired into .github/workflows/c8-precheck.yml — see CLAUDE.md §”Lint gates (issue #1174 PR10)”). Maintainers perform the functional test, security review, and documentation sync verification during PR review.

2. Test Standards

2.1 cargo test

• Environment: AI_MEMORY_NO_CONFIG=1 to prevent config interference
• Platforms: Must pass on both ubuntu-latest and macos-latest
• Result: 0 failures required

AI_MEMORY_NO_CONFIG=1 cargo test

2.2 Full Pre-PR Verification

Contributors must run all six before submitting (four cargo gates plus the two script gates introduced by #1200 for the substrate-canonical-discipline campaign):

cargo fmt --check
cargo clippy -- -D warnings -D clippy::all -D clippy::pedantic
AI_MEMORY_NO_CONFIG=1 cargo test
cargo audit
scripts/check-vendor-literals.sh        # vendor-monoculture + SECS_PER_* HARD-BLOCK (#1200)
scripts/qc-codegraph-precheck.sh        # C8 caller-context allowlist + structural drift (#923)

2.3 Full Spectrum Functional Test

Run against the compiled binary via CLI. Covers all 26 CLI commands with edge cases. When adding a new command, add a corresponding row to this table.

2.4 Memory & TTL Test Protocol

15-20 tests covering the memory lifecycle:

2.5 Pass/Fail Criteria

• Pass: Test produces expected result.
• Acceptable known behavior: TTL refresh on recall sets expires_at = now + extend_secs (rolling window). When recalled shortly after creation, this can be earlier than the initial TTL. This is by-design, not a bug.
• Ship-blocking fail: Any functional test failure not documented as by-design.

2.6 Test Count Documentation Locations

When test counts change, update ALL of these:

MCP tool count in:

3. Security Review Standards

3.1 Automated (CI)

• cargo audit runs on every push to main and on every PR. Scans Cargo.lock for known vulnerabilities.
• 0 vulnerabilities required. Warnings for transitive unmaintained crates are acceptable if not exploitable.

3.2 Manual Security Review Checklist

Every patch/release must be reviewed against these 10 areas:

3.3 Severity Classification

4. Release Standards

4.1 Version Numbering

• Format: MAJOR.MINOR.PATCH-patch.N in Cargo.toml (e.g., 0.5.4-patch.4)
• Git tag format: vMAJOR.MINOR.PATCH.N (e.g., v0.5.4.4)
• Binary reports: ai-memory MAJOR.MINOR.PATCH-patch.N

4.2 Release Process

1. Merge develop into main via PR (owner approval required)
2. Ensure all gates pass locally:

   cargo fmt
   cargo clippy -- -D warnings -D clippy::all -D clippy::pedantic
   AI_MEMORY_NO_CONFIG=1 cargo test
   cargo audit
   

3. Push tag v{VERSION} to main
4. CI pipeline triggers automatically:
   • Check phase (fmt, clippy pedantic, test, audit, build) on ubuntu + macos
   • Release phase: 5 platform binaries + .deb/.rpm packages
   • Docker: push to GHCR (ghcr.io/alphaonedev/ai-memory:VERSION + :latest)
   • COPR: Fedora COPR upload (alpha-one-ai/ai-memory)
5. Verify: gh release view v{VERSION} --repo alphaonedev/ai-memory-mcp
6. Update Homebrew tap (manual): alphaonedev/homebrew-tap — download platform tarballs, compute SHA256 hashes, update Formula/ai-memory.rb

4.3 Documentation Sync

Before tagging a release:

• CHANGELOG.md has entry for this version with all fixes
• Test counts updated in 7 locations (see Section 2.6)
• MCP tool counts updated in 4 locations (see Section 2.6)
• Cargo.toml version matches the tag
• All new source files have SPDX headers
• Homebrew tap updated (alphaonedev/homebrew-tap) with new SHA256 hashes

4.4 Post-Release

• Install release binary on node from GitHub Releases (not cargo install)
• Verify: ai-memory --version
• Store release memory in ai-memory for session recall

5. Legal & Licensing

6. Key References

7. Autonomous Campaign Workflow

When development is driven by an autonomous Claude Code campaign (the campaign Python harness at alphaonedev/agentic-mem-labs/tools/campaign/, Apache 2.0 © AlphaOne LLC), every standard in §1–§6 still applies. The campaign agent runs with --dangerously-skip-permissions and merge authority on a single release branch only; the constraints below are baked into every iteration’s prompt and survive bypassPermissions.

7.1 Hard rules under campaign

7.2 Per-iteration loop (8 steps)

The agent’s prompt requires every iteration to execute, in order:

1. Load memories — recall 3 targeted queries + list recent in the campaign’s namespace (see §7.4)
2. Read charter + last iteration report
3. Inspect repo state (git fetch / status / log)
4. Pick exactly one unblocked charter item
5. Implement on campaign/<slug> feature branch → cargo fmt → cargo clippy --all-targets -- -D warnings → cargo test --all → signed commit → push → gh pr create → gh pr merge --squash --delete-branch
6. Record decisions to memory throughout (not only at the end)
7. Write iteration report markdown using the fixed template
8. Commit + push the report on the dedicated campaign-log/vX.Y.Z branch of the charter repo (append-only audit)

7.3 Quality gates (identical to non-campaign work)

• Tests must pass before push (AI_MEMORY_NO_CONFIG=1 cargo test --all)
• cargo fmt --check clean
• cargo clippy --all-targets -- -D warnings -D clippy::all -D clippy::pedantic clean
• No unwrap() in non-test code without an explicit invariant comment
• Conventional commit messages
• One logical change per dev-repo commit
• All commits SSH-signed (commit.gpgsign=true, ed25519)
• SPDX headers on new source files

7.4 Memory namespace convention (load-bearing)

Each campaign owns one ai-memory namespace named after the campaign (e.g. campaign-v063 for the v0.6.3 grand-slam campaign). The namespace is the campaign’s complete operating context AND its historical audit artifact:

Rule: every campaign memory is namespace-scoped to that campaign’s name. After the campaign ends, the namespace is the canonical historical reference for “what got built, why, and in what order.” Future campaigns do not share namespaces.

Discoverable via:

ai-memory --db ~/.claude/ai-memory.db list   --namespace campaign-v063
ai-memory --db ~/.claude/ai-memory.db recall --namespace campaign-v063 "what task was last shipped"

7.5 Living snapshot — open issues & PRs (charter context)

The campaign agent reads this section at iter 1 of every new campaign to seed scope. Maintainers refresh it when a campaign is created or when issue/PR triage is done. Most recent snapshot — 2026-04-25:

Open issues (alphaonedev/ai-memory-mcp)
  #355  chore(deps): rustls-pemfile 2.2.0 unmaintained (RUSTSEC-2025-0134) — transitive via axum-server [low]
  #331  v0.7 red-team P3 polish punchlist (rollup) [enhancement,low]
  #318  MCP stdio tool dispatch writes bypass federation fanout coordinator [bug,high]
  #311  feat(v0.6.0.1): targeted memory share — CLI + MCP tool for point-to-point sync by ID/namespace/last-N [enhancement]
  #239  [P2] /sync/since allows full DB dump for any valid mTLS peer (red-team #230) [docs,med,security]
  #238  [P2] Body-claimed sender_agent_id not attested to mTLS cert (red-team #230) [enh,med,security]
  #228  v0.8: end-to-end memory encryption (X25519 + ChaCha20-Poly1305) — Layer 3 peer-mesh crypto [enhancement]
  #224  Phase 3: Memory Sharing & Sync — design + decomposition (v0.8.0; foundation lands v0.6.0 GA) [enhancement]

Open PRs (against develop)
  #330  feat(msrv,ppa): Ubuntu 26.04 Resolute Raccoon as sole PPA target; rustc 1.91 MSRV
  #285  feat: Layer 2b attested sender_agent_id primitives (v0.7)
  #253  docs: scaffold Docusaurus documentation site (#252)

The campaign’s mandate is the charter, not the open-issues backlog — but the agent must consult this list when picking tasks to avoid duplicating in-flight work.

7.6 Operator surface (campaign harness CLI)

campaign preflight        # 8 health checks
campaign install          # 24x7 launchd daemon (renders plist from live Config)
campaign install --force  # bootout existing + re-install (use after env changes)
campaign service-status   # human-readable status with drift detection
campaign watch            # live TUI of newest iter log (auto-rotates)
campaign status           # pid / branch / iter count
campaign stop             # kill-switch + drain + SIGTERM/SIGKILL
campaign uninstall        # bootout (optionally --remove-plist)

Pause without uninstalling: touch <state-dir>/kill-switch. Resume: rm <state-dir>/kill-switch. The KeepAlive PathState watcher in the LaunchAgent plist toggles the daemon’s run-state automatically.

Full operator guide: alphaonedev/agentic-mem-labs/tools/campaign/README.md (Apache 2.0 © AlphaOne LLC).