Merge pull request #326 from rtk-ai/develop

Next Release

Author: pszymkowiak

.github/workflows/cd.yml

@@ -209,6 +209,14 @@ jobs:
 
           git push origin "$BRANCH"
 
+          # Ensure the 'automated' label exists before referencing it: a missing
+          # label makes `gh pr create --label` fail and aborts the back-merge PR
+          # ("could not add label: 'automated' not found"). Idempotent.
+          gh label create automated \
+            --color ededed \
+            --description "Automated PR (back-merge / release tooling)" \
+            2>/dev/null || true
+
           gh pr create \
             --base develop \
             --head "$BRANCH" \

.github/workflows/ci.yml

@@ -52,6 +52,40 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - run: cargo test --workspace
 
+  # Validates the fully-static musl binary shipped for old-glibc distros
+  # (issue #330: the glibc binaries need symbols newer than Debian Bookworm's
+  # glibc 2.36). Embeddings are dropped because `ort`/onnxruntime ships only
+  # glibc prebuilt binaries and can't link statically against musl.
+  musl:
+    name: musl static build
+    needs: clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: x86_64-unknown-linux-musl
+      - uses: Swatinem/rust-cache@v2
+      - name: Install musl tools
+        run: sudo apt-get update && sudo apt-get install -y musl-tools
+      - name: Build static musl binary (no embeddings)
+        # sqlite-vec.c uses BSD type names (u_int8_t/u_int16_t/u_int64_t) that
+        # glibc provides but musl does not; map them to the standard names.
+        env:
+          CFLAGS_x86_64_unknown_linux_musl: "-Du_int8_t=uint8_t -Du_int16_t=uint16_t -Du_int32_t=uint32_t -Du_int64_t=uint64_t"
+        run: >-
+          cargo build --release --target x86_64-unknown-linux-musl -p icm-cli
+          --no-default-features --features "backend-sqlite,tui,http-api"
+      - name: Verify the binary is fully static
+        run: |
+          bin=target/x86_64-unknown-linux-musl/release/icm
+          file "$bin"
+          if ldd "$bin" 2>&1 | grep -Eq "statically linked|not a dynamic executable"; then
+            echo "OK: statically linked — runs on any Linux regardless of glibc"
+          else
+            echo "FAIL: binary is dynamically linked"; ldd "$bin"; exit 1
+          fi
+
   security:
     name: security scan
     needs: clippy

.github/workflows/release.yml

@@ -45,12 +45,22 @@ jobs:
           - target: aarch64-apple-darwin
             os: macos-latest
             archive: tar.gz
+          # Build the glibc binaries on an older runner (glibc 2.35) so they
+          # run on Debian 12 "Bookworm" (glibc 2.36) and other current distros
+          # — ubuntu-latest's glibc is too new (issue #330).
           - target: x86_64-unknown-linux-gnu
-            os: ubuntu-latest
+            os: ubuntu-22.04
             archive: tar.gz
           - target: aarch64-unknown-linux-gnu
+            os: ubuntu-22.04
+            archive: tar.gz
+          # Fully-static musl binary for old-glibc distros (issue #330:
+          # Debian Bookworm's glibc 2.36 is older than ubuntu-latest's).
+          # No embeddings: ort/onnxruntime has no static musl build.
+          - target: x86_64-unknown-linux-musl
             os: ubuntu-latest
             archive: tar.gz
+            flags: --no-default-features --features backend-sqlite,tui,http-api
           - target: x86_64-pc-windows-msvc
             os: windows-latest
             archive: zip
@@ -70,6 +80,12 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
 
+      - name: Install musl tools
+        if: matrix.target == 'x86_64-unknown-linux-musl'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y musl-tools
+
       - name: Build (cross aarch64)
         if: matrix.target == 'aarch64-unknown-linux-gnu'
         run: cargo build --release --target ${{ matrix.target }} -p icm-cli --features vendored-openssl
@@ -78,7 +94,11 @@ jobs:
 
       - name: Build
         if: matrix.target != 'aarch64-unknown-linux-gnu'
-        run: cargo build --release --target ${{ matrix.target }} -p icm-cli
+        # Target-specific, so a no-op for non-musl targets: sqlite-vec.c uses
+        # BSD type names (u_int8_t/…) that glibc provides but musl does not.
+        env:
+          CFLAGS_x86_64_unknown_linux_musl: "-Du_int8_t=uint8_t -Du_int16_t=uint16_t -Du_int32_t=uint32_t -Du_int64_t=uint64_t"
+        run: cargo build --release --target ${{ matrix.target }} -p icm-cli ${{ matrix.flags }}
 
       - name: Package (Unix)
         if: matrix.archive == 'tar.gz'
@@ -101,7 +121,8 @@ jobs:
 
   build-deb:
     name: Build .deb
-    runs-on: ubuntu-latest
+    # Older glibc (2.35) so the packaged binary runs on Debian 12 (#330).
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4

CONTRIBUTING.md

@@ -0,0 +1,185 @@
+# Contributing to ICM
+
+**Welcome!** We appreciate your interest in contributing to ICM.
+
+## Quick Links
+
+- [Report an Issue](../../issues/new)
+- [Open Pull Requests](../../pulls)
+- [Start a Discussion](../../discussions)
+
+---
+
+## What is ICM?
+
+**ICM (Infinite Context Memory)** is a persistent long-term memory for LLM agents, written in Rust. It stores memories with embeddings in SQLite, does hybrid retrieval (BM25/FTS5 + vector similarity), manages temporal decay and consolidation, and exposes an MCP server so tools like Claude Code, Codex, and others can store and recall memories across sessions.
+
+---
+
+## Ways to Contribute
+
+| Type | Examples |
+|------|----------|
+| **Report** | File a clear issue with steps to reproduce, expected vs actual behavior |
+| **Fix** | Bug fixes, correctness issues, durability/robustness improvements |
+| **Build** | New features (for core features — storage backends, retrieval, MCP tools — discuss with maintainers first) |
+| **Review** | Review open PRs, test changes locally, leave constructive feedback |
+| **Document** | Improve docs, clarify behavior |
+
+---
+
+## Design Philosophy
+
+A few principles guide ICM. Understanding them helps your contribution fit naturally.
+
+### Correctness over cleverness
+
+ICM is positioned as a durable, cross-host brain shared by multiple agents writing the same store concurrently. Data loss and silent corruption are the worst failure modes. Prefer the safe, boring path; back up before destructive operations; never claim a fix you can't verify.
+
+### No panics in production code
+
+No `.unwrap()` / `.expect()` / `panic!` in non-test code. Use typed errors (`thiserror`) in libraries and `anyhow` with `.context()` at the CLI boundary, and propagate with `?`. A hook or MCP tool must degrade gracefully, never crash the caller.
+
+### Async-first I/O, cheap hot paths
+
+All I/O is async where it matters. Keep the per-hook and per-prompt paths cheap — they run on every tool call. Don't load heavy models or do network I/O on a path that must return in milliseconds.
+
+### Backends are additive, selected at runtime
+
+SQLite is the default in-process backend; Postgres/OpenSearch are compiled in and chosen at runtime via `ICM_DB_BACKEND`. New storage features should respect this split and not assume SQLite.
+
+### Extensibility
+
+Reuse existing components and traits (`MemoryStore`, `Embedder`, …) instead of duplicating. New core features (backends, retrievers, MCP tools) are worth discussing before you build.
+
+---
+
+## Commit Messages & Changelog
+
+ICM uses [Conventional Commits](https://www.conventionalcommits.org/) and [release-please](https://github.com/googleapis/release-please) to **auto-generate CHANGELOG.md, version bumps, and GitHub releases**. Never edit `CHANGELOG.md` manually — it is fully managed by release-please from your commit messages.
+
+### Commit format
+
+```
+<type>(<scope>): <short description>
+```
+
+| Type | Semver Impact | When to Use |
+|------|---------------|-------------|
+| `feat` | Minor | New features, new MCP tools, new backends |
+| `fix` | Patch | Bug fixes, corrections |
+| `perf` | Patch | Performance improvements |
+| `refactor` | — | Code restructuring (no changelog entry) |
+| `docs` | — | Documentation only |
+| `chore` | — | Maintenance, CI, deps |
+| `feat!` / `fix!` | Major | Breaking changes (add `!` after type) |
+
+**Scope** should match the module or area: `store`, `mcp`, `retriever`, `hooks`, `cli`, `cicd`, etc.
+
+### Examples
+
+```
+feat(mcp): add icm_memory_health tool
+fix(store): open read-only connections WAL-aware instead of immutable
+perf(retriever): reuse the FTS statement across recall calls
+feat!(store): change the embedding column layout
+```
+
+These commit messages become CHANGELOG entries when release-please cuts a release. Write them as if users will read them.
+
+---
+
+## Branch Naming Convention
+
+Git branch names cannot include spaces or colons, so we use slash-prefixed names.
+
+| Prefix | When to Use |
+|--------|-------------|
+| `fix/` | Bug fixes, corrections, minor adjustments |
+| `feat/` | New features |
+| `chore/` | CI/CD, deps, maintenance, breaking changes |
+
+Combine the prefix with a scope if it adds clarity and finish with a short, kebab-case slug:
+
+```
+fix/store-readonly-live-connection
+feat/mcp-http-proxy-mode
+chore/release-pipeline-cleanup
+```
+
+---
+
+## Pull Request Process
+
+### Scope Rules
+
+**Each PR must focus on a single feature, fix, or change.** The diff must stay in-scope with the PR title and body. Out-of-scope changes (unrelated refactors, drive-by fixes, formatting of untouched files) go in a separate PR. For large features, prefer several logical, independently-reviewable PRs over one enormous one.
+
+### 1. Create your branch
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feat/scope-your-clear-description
+```
+
+### 2. Make your changes
+
+Respect the existing workspace layout (`crates/icm-*`). Keep functions short and focused. Comments explain *why*, not *what*.
+
+### 3. Add tests
+
+Every change **must** include tests where it has a runtime surface. See [Testing](#testing).
+
+### 4. Add documentation
+
+Update docs for new features and changes to already-documented behavior.
+
+### 5. Target `develop`
+
+Open your Pull Request against the **`develop`** branch. `main` is reserved for stable releases — only maintainer `develop` → `main` PRs (cut via release-please) target it.
+
+### 6. Review & CI
+
+1. **Maintainer review** — a maintainer reviews for quality and alignment.
+2. **CI/CD checks** — automated tests and lints must pass.
+3. **Resolution** — address feedback from review or CI.
+
+### 7. Integration & release
+
+```
+your branch --> develop (review + CI + integration) --> main (versioned release via release-please)
+```
+
+---
+
+## Testing
+
+### Pre-Commit Gate (mandatory)
+
+All three must pass before any PR:
+
+```bash
+cargo fmt --all --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace
+```
+
+### PR Testing Checklist
+
+- [ ] Unit tests added/updated for changed code
+- [ ] Integration/e2e coverage where the change has a runtime surface
+- [ ] No `.unwrap()` / `.expect()` / `panic!` in non-test code
+- [ ] `cargo fmt --all --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace` passes
+- [ ] Manual test: exercise the affected flow (CLI command, MCP tool, hook) and inspect the result
+
+---
+
+## Questions?
+
+- **Bug reports & features**: [Issues](../../issues)
+- **Discussions**: [GitHub Discussions](../../discussions)
+
+**For external contributors**: your PR undergoes automated and manual security review (see [SECURITY.md](SECURITY.md)).
+
+---
+
+**Thank you for contributing to ICM!**

DISCLAIMER.md

@@ -0,0 +1,29 @@
+# Disclaimer
+
+## No Warranty
+
+This software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. The entire risk as to the quality and performance of the software is with you.
+
+## Limitation of Liability
+
+In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software. This includes, without limitation, any direct, indirect, incidental, special, exemplary, or consequential damages (including but not limited to loss of data, loss of profits, or business interruption).
+
+## Precompiled Binaries
+
+Precompiled binaries are provided solely for convenience and are covered by the same license as the source code (Apache License 2.0). They are provided without warranties or conditions of any kind. You are responsible for verifying the integrity and suitability of any binary before use. Always verify checksums when available (the installer verifies each download against the release's `checksums.txt`).
+
+## Your Data
+
+ICM stores your memories in a local SQLite database on your machine. It does **not** phone home: the "hook telemetry" it records (see `icm hook-log` / `icm hook-stats`) stays in your local database and is never transmitted. Any embedding provider or LLM CLI you explicitly configure is contacted under your own credentials — review those providers' terms. You are responsible for the confidentiality and backups of your store.
+
+## Third-Party Dependencies
+
+This software incorporates third-party open-source components, each governed by their respective licenses. The authors make no representations or warranties regarding these dependencies and accept no liability for any issues arising from their use.
+
+## Use at Your Own Risk
+
+This software interacts with your development environment, file system, and any AI tools you connect it to. It is your responsibility to ensure that its use is appropriate for your environment and complies with any applicable policies, regulations, or agreements. The authors are not responsible for any unintended side effects resulting from its use.
+
+---
+
+See [LICENSE](LICENSE) for the full terms of the Apache License 2.0 under which this software is distributed.