chore(release): v0.9.13 — .env.example + init command + sync-checker (#372)

[rohitg00]

Summary

Closes #372. Ships the config-discovery surface that's been gating new-user onboarding since v0.9.0.

Three new artifacts

File	Purpose
.env.example (repo root, bundled in npm tarball via files)	Single documented source for every env var read by src/. Every line commented out so the file is a template.
agentmemory init (new CLI command)	Copies bundled .env.example to ~/.agentmemory/.env if absent. Refuses to overwrite; prints a diff command pointing at the latest template.
scripts/check-env-example.mjs (CI gate)	Fails CI when src/ reads an env var that isn't documented (or vice-versa). Plugged into .github/workflows/ci.yml after npm test. Bootstrap: 60 keys in sync.

Closes / supersedes

• Closes Ship .env.example with documented provider + embedding + tuning keys #372 — ship .env.example
• Closes Environment variables not documented — 30+ env vars across codebase #47 — env vars not documented (30+ across codebase)
• Closes Is there a config file to specify all environment variables at once? #293 — central config file
• Partial Docs: setup gaps found during end-to-end OpenCode + Docker + Ollama install #233 — setup gaps documentation

Release cut

Same PR bumps 0.9.12 → 0.9.13 across the 9 standard files (version.ts, package.json × 2, plugin.json × 2, types.ts ExportData union, supportedVersions Set, test expected version). v0.9.13 release notes in CHANGELOG.md cover the wave landed since v0.9.12:

• This PR (Ship .env.example with documented provider + embedding + tuning keys #372) — .env.example discovery
• feat(search): CJK tokenizer for BM25 #362 — CJK BM25 tokenizer
• feat(bench): load-100k.ts harness with p50/p90/p99 output #363 — benchmark/load-100k.ts harness
• feat(deploy): fly.io / Railway / Render one-click templates #361 — fly.io / Railway / Render / Coolify deploy templates
• docs(python): iii-sdk example replaces standalone REST client #364 — Python ecosystem via iii-sdk example
• chore(providers): bump Gemini defaults to current GA models #370 — Gemini GA model bumps
• chore(security): add dependabot config + close 14 open advisories #348 — 14 Dependabot security advisories closed

Verification

• npm test — 903 / 903 passing
• npm run build — clean (.env.example copied into dist/ by build script)
• node scripts/check-env-example.mjs — env-example: in sync (60 keys documented)
• agentmemory init smoke — creates ~/.agentmemory/.env on first run, refuses overwrite on second with diff hint

Test plan

• npm test
• npm run build
• Init smoke against a clean HOME
• Tag v0.9.13 after merge, publish via existing workflow

Summary by CodeRabbit

• New Features

  • Added an init CLI command to create per-user configuration from a bundled template.
  • Bundled a comprehensive .env example documenting provider, embedding, security, tuning, behavior, CLI/runtime, and integration options.

• Documentation

  • Published changelog entry for v0.9.13 with added examples, deploy templates, tokenizer and benchmarking notes, and security updates.

• Chores

  • Bumped package/plugin versions to 0.9.13 and included the .env example in published files.
  • Added a CI/check tool to verify .env example is in sync with code.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentmemory	Ready	Preview, Comment	May 15, 2026 9:09am

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 518b2164-577d-445a-957a-59d774667988

📥 Commits

Reviewing files that changed from the base of the PR and between 8bc9160 and 2de270f.

📒 Files selected for processing (2)

• scripts/check-env-example.mjs
• src/cli.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• scripts/check-env-example.mjs

---

📝 Walkthrough

Walkthrough

This release adds a comprehensive .env.example template (bundled into the package), a new agentmemory init command to copy it to ~/.agentmemory/.env, a CI script to validate documented env vars against source usage, and bumps version/compatibility to 0.9.13 across manifests and import logic.

Changes

Release 0.9.13: Configuration Template & CLI Bootstrap

Layer / File(s)	Summary
Configuration template and NPM publishing .env.example, package.json	New .env.example documents LLM/embedding providers, auth, search tuning, behavior flags, runtime knobs, port configuration, iii-engine pinning, and optional integrations. Build script and files whitelist updated to bundle the template into the npm tarball.
CLI init command for config bootstrap src/cli.ts	agentmemory init copies the bundled .env.example to ~/.agentmemory/.env if the destination is missing, with fallback location detection and warning when the file already exists.
CI sync-checker for env var documentation scripts/check-env-example.mjs	New script scans src/ for environment variable usage (via process.env, env[], getEnvVar()), compares against .env.example documented keys, and reports missing (undocumented) or orphan (unused) variables with detailed exit-code status.
Version updates and export-import compatibility src/version.ts, package.json, packages/mcp/package.json, plugin/*, src/functions/export-import.ts, test/export-import.test.ts	All version manifests and exported VERSION constant bumped from 0.9.12 to 0.9.13; mem::import supported export versions extended to accept 0.9.13 exports; test expectations updated.
Release notes and changelog documentation CHANGELOG.md	Publishes 0.9.13 release entry (dated 2026-05-15) documenting .env.example template, agentmemory init, CI sync-checker, CJK tokenizer, load harness, deploy templates, Python quickstart, Gemini provider defaults changes, security advisories, and external contributors.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• rohitg00/agentmemory#137: Both PRs extend the supportedVersions whitelist in src/functions/export-import.ts to recognize newly released versions in mem::import.
• rohitg00/agentmemory#261: Both PRs update export-import version compatibility by extending supportedVersions in src/functions/export-import.ts and adjusting corresponding test expectations for a new release version.
• rohitg00/agentmemory#173: Both PRs update the VERSION constant in src/version.ts as part of standard release versioning.

Poem

🐰 A template blooms in .env ground,
With init commands swiftly found,
CI checks sync truth and care,
From Gemini defaults laid bare,
Version 0.9.13 takes the air! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 28.57% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately captures the three main artifacts shipped in this release: .env.example template, init command, and sync-checker CI gate.
Linked Issues check	✅ Passed	The PR comprehensively addresses all objectives from #372, #47, and #293: .env.example created with all documented env vars, init command copies template to ~/.agentmemory/.env, sync-checker enforces consistency, version bumped across all manifests, and release notes added.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the release objectives: version bumps (7 files), .env.example creation, init CLI implementation, sync-checker script, CHANGELOG update, and test version update.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/env-example-372

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (2)

src/cli.ts (1)

899-903: ⚡ Quick win

Trim WHAT-level comments in CLI init path.

These comments describe implementation mechanics more than intent; prefer self-descriptive naming and keep only rationale-heavy comments.

As per coding guidelines, "Avoid code comments explaining WHAT — use clear naming instead".

Also applies to: 935-935

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli.ts` around lines 899 - 903, The leading block comment before
findEnvExample is a WHAT-level implementation detail; remove or shorten it to a
rationale-focused comment and rely on a clear function name (findEnvExample) to
convey behavior. Edit the comment(s) around findEnvExample and the similar
comment at the other occurrence (near line 935) to keep only why the lookup
exists (e.g., "Prefer packaged .env.example; fall back to repo root when running
from source") and remove step-by-step implementation notes so the code is
self-explanatory.

.env.example (1)

168-168: 💤 Low value

Add trailing newline at end of file.

The file is missing a final newline, which is a POSIX text file convention and prevents unnecessary git diff noise.

📝 Proposed fix

 # OBSIDIAN_AUTO_EXPORT=true                      # Auto-export memories to an Obsidian vault on every consolidation
+

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.env.example at line 168, Add a single trailing newline character at the end
of the .env.example file so the file ends with a newline (POSIX convention) —
update the file's EOF so the last line is terminated with a newline character.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/check-env-example.mjs`:
- Around line 32-46: Update the comment above the walk function to accurately
reflect the file extensions matched by the regex: change "Walk src/ for .ts /
.mts / .mjs files" to include .js (e.g., "Walk src/ for .ts / .mts / .mjs / .js
files") so it matches the /\. (ts|mts|mjs|js)$/.test logic in the walk function;
if instead you intended to exclude .js, remove "js" from the regex in walk so
the comment and pattern remain consistent (also consider adding an explicit
check to skip test/ paths if test exclusion is required).

In `@src/cli.ts`:
- Around line 934-939: The current init flow uses existsSync(target) +
copyFile(...) which can race; remove the pre-check and perform an exclusive copy
instead by calling copyFile(template, target, constants.COPYFILE_EXCL) (import
constants from "node:fs" or "node:fs/promises" as appropriate) so the copy fails
atomically if the target already exists; catch the specific EEXIST/EACCES error
from copyFile in the try/catch and treat it as "do not overwrite" instead of
propagating, leaving mkdir(dir, { recursive: true }) and other logic unchanged
and referencing the existing mkdir, copyFile, template, target symbols.

---

Nitpick comments:
In @.env.example:
- Line 168: Add a single trailing newline character at the end of the
.env.example file so the file ends with a newline (POSIX convention) — update
the file's EOF so the last line is terminated with a newline character.

In `@src/cli.ts`:
- Around line 899-903: The leading block comment before findEnvExample is a
WHAT-level implementation detail; remove or shorten it to a rationale-focused
comment and rely on a clear function name (findEnvExample) to convey behavior.
Edit the comment(s) around findEnvExample and the similar comment at the other
occurrence (near line 935) to keep only why the lookup exists (e.g., "Prefer
packaged .env.example; fall back to repo root when running from source") and
remove step-by-step implementation notes so the code is self-explanatory.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8d719de2-2043-48d2-aa7f-c26ec0e77ae4

📥 Commits

Reviewing files that changed from the base of the PR and between 4b354b7 and 8bc9160.

📒 Files selected for processing (11)

• .env.example
• CHANGELOG.md
• package.json
• packages/mcp/package.json
• plugin/.claude-plugin/plugin.json
• plugin/.codex-plugin/plugin.json
• scripts/check-env-example.mjs
• src/cli.ts
• src/functions/export-import.ts
• src/version.ts
• test/export-import.test.ts