🧠 A memory store for AI agents that runs entirely on your own machine. Remember things, then find them back by meaning instead of by keyword — without paying a hosted service per memory.

Other Languages: English | 繁體中文 | 简体中文

🚧 Status

Early development. The command surface below is settled, but nothing behind it is implemented yet — every subcommand currently exits with a "not implemented" error. The storage format and the embedding backends are still being designed, so expect breaking changes until 0.1.0.

📦 Installation

A single self-contained binary, distributed through whichever package manager you already have.

cargo install amfs                    # Rust
npm install -g @mai0313/amfs          # Node.js
uv tool install agent-memory-fs       # Python

Or run it without installing:

uvx --from agent-memory-fs amfs --help

The package name differs per registry, the command does not. Whichever one you install, you get amfs. Only crates.io could take the short name: amfs was already registered on PyPI by an unrelated project, and npm rejects the unscoped amfs as too similar to existing package names. In particular, do not run uvx amfs — that resolves to somebody else's package.

Prebuilt binaries for macOS, Linux, and Windows are also attached to every release.

🚀 Usage

amfs add "Wei prefers Traditional Chinese in code reviews" --user-id wei

amfs search "what language does Wei want reviews in?" --user-id wei
amfs search "code review preferences" --limit 5

amfs list --user-id wei
amfs get <id>
amfs update <id> "Wei prefers Traditional Chinese, English for commit messages"
amfs delete <id>

Run amfs --help or amfs <command> --help for the full set of flags.

🧭 How It Works

Memories live in a local file-backed store; searching embeds the query and compares it against the stored memories, so search finds things that mean the same thing rather than things that share a word.

Embedding backends are pluggable. Google's Gemini embedding model is the one used during development, and running fully offline against a local model is a goal, not a promise — see Status.

🛠️ Development

Requirements: Rust 1.95 or newer (the project uses Edition 2024). The toolchain is pinned in rust-toolchain.toml, so rustup picks it up automatically.

make fmt            # rustfmt + clippy (auto-fix, then deny warnings)
make test           # cargo test (all targets)
make test-verbose   # cargo test (all targets with verbose output)
make coverage       # generate LCOV coverage report
make build          # cargo build (debug)
make release        # cargo build --release --locked
make run            # run the release binary
make clean          # clean build artifacts and caches
make package        # build crate package (allow dirty)
make help           # list targets

Testing Layout

This project follows Rust's idiomatic test organization:

• Unit tests live next to the code they verify inside src/, wrapped in a #[cfg(test)] mod tests { ... } block. They can exercise private items.
• Integration tests live in the top-level tests/ directory. Each file is compiled as its own crate and may only use the public API:
  • tests/cli.rs — drives the compiled binary: argument parsing, --help, exit codes.
  • tests/version.rs — build-time version metadata plumbed through build.rs.

Run everything with make test (or cargo test --all).

Version Information

amfs --version reports dynamic build metadata: the git tag (or the Cargo.toml version when there is no tag), commits since that tag, the short commit hash, a dirty marker for uncommitted changes, plus the Rust and Cargo versions used to build it. All of it is embedded at build time by build.rs.

amfs 0.1.25-2-gf4ae332-dirty

🐳 Docker

docker build -f docker/Dockerfile --target prod -t amfs:latest .
docker run --rm amfs:latest --help

Images are also published to ghcr.io/mai0313/amfs.

🧩 Release Builds

build_release.yml builds release binaries on tags matching v*, uploads them to the GitHub Release, and publishes to crates.io, npm, and PyPI.

Targets:

• x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu
• x86_64-apple-darwin, aarch64-apple-darwin
• x86_64-pc-windows-msvc, aarch64-pc-windows-msvc

Asset naming:

• amfs-v<version>-<platform>.tar.gz (all platforms)
• amfs-v<version>-<platform>.zip (Windows additionally)

Distribution names are pinned in build_release.yml, not derived from the repository name.

🔁 CI/CD Workflows

Main Workflows

• Tests (test.yml): cargo build/test + generate LCOV coverage report and upload artifact
• Code Quality (code-quality-check.yml): pre-commit hooks + rustfmt check + clippy (deny warnings)
• Build and Release (build_release.yml): multi-platform binaries, GitHub Release, crates.io / npm / PyPI publish on tags v*
• Publish Docker Image (build_image.yml): push to GHCR on main and tags v*

Additional Automation

• Auto Labeler (auto_labeler.yml): automatically label PRs based on branch names and file changes
• Code Scan (code_scan.yml): multi-layer security scanning (GitLeaks, Trufflehog secret scanning, CodeQL code analysis)
• Release Drafter (release_drafter.yml): auto-generate release notes
• Semantic PR (semantic-pull-request.yml): enforce PR title format
• Dependabot dependency updates

🤝 Contributing

See CONTRIBUTING.md. In short: Conventional Commits for PR titles, and before opening a PR run

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all

📄 License

MIT — see LICENSE.