Self-Learning Memory System

A Rust-based self-learning memory system with episodic memory, pattern extraction, and intelligent retrieval capabilities.

Overview

The Self-Learning Memory System provides:

• Episodic Memory: Store and retrieve task execution episodes with context
• Pattern Extraction: Automatically extract patterns from successful task completions
• Intelligent Retrieval: Semantic search with multiple embedding providers
• MCP Server: Model Context Protocol server for AI assistant integration
• CLI Tools: Command-line interface for all operations

Key Features

Quick Start

# Install the CLI
cargo install do-memory-cli

# Start the MCP server
do-memory-mcp-server

# Create an episode
do-memory-cli episode create --task "My task"

Architecture

The system consists of several crates:

• do-memory-core: Core types and logic
• do-memory-storage-turso: Turso/libSQL backend
• do-memory-storage-redb: redb cache backend
• do-memory-mcp: MCP server
• do-memory-cli: Command-line interface

See the Getting Started chapter for details.

Getting Started

Installation

From crates.io

cargo install do-memory-cli
cargo install do-memory-mcp-server

From source

git clone https://github.com/d-o-hub/rust-self-learning-memory
cd rust-self-learning-memory
cargo build --release

Configuration

Environment Variables

Local Development

# Start local Turso
turso dev --db-file ./data/memory.db --port 8080

# Set environment
export TURSO_DATABASE_URL="http://127.0.0.1:8080"
export TURSO_AUTH_TOKEN=""

First Episode

# Create an episode
do-memory-cli episode create --task "Implement feature X"

# Log steps
do-memory-cli episode log-step --episode-id <ID> --step "Read requirements"

# Complete the episode
do-memory-cli episode complete --episode-id <ID> --outcome success

# Extract patterns
do-memory-cli pattern extract --episode-id <ID>

MCP Server

# Start the server
do-memory-mcp-server

# The server communicates via JSON-RPC over stdin/stdout

Verify a Release

Every GitHub Release of this project is built by the repository’s own release workflow (.github/workflows/release.yml) from a vX.Y.Z tag. This chapter shows how to confirm that a release you downloaded is authentic and has not been tampered with: checksums, build provenance, SBOMs, and immutable-release attestations.

What a release publishes

Each release attaches one archive per supported target for every dist-able crate:

The supported targets are x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-apple-darwin, aarch64-apple-darwin, and x86_64-pc-windows-msvc (.zip rather than .tar.xz).

Alongside the archives, cargo-dist attaches:

• a sibling <archive>.sha256 checksum for every archive, plus a combined sha256.sum;
• source.tar.gz and its source.tar.gz.sha256;
• dist-manifest.json, the cargo-dist build manifest.

Releases cut by the release workflow after the SBOM/attestation pipeline landed (issue #1121) additionally publish and attest:

• one CycloneDX SBOM per crate — do-memory-cli.cdx.json, do-memory-mcp.cdx.json, and do-memory-examples.cdx.json;
• build-provenance attestations for every archive (https://slsa.dev/provenance/v1 predicate);
• SBOM attestations for each crate’s archives (https://cyclonedx.org/bom predicate).

Note: Checksums ship with every release. SBOM assets and attestations are produced only by the pipeline from issue #1121 onward. The older v0.1.44 release predates that pipeline, so it carries only the archives, their checksums, sha256.sum, source.tar.gz, and dist-manifest.json.

Verify checksums

Download an archive together with its .sha256 sidecar, then verify it. The sidecar is a standard sha256sum line that names the archive it covers, so sha256sum -c works directly.

Integrity vs authenticity: the .sha256 sidecars and sha256.sum are published by the same release as the archives, so a passing checksum proves the download was not truncated or corrupted in transit — it does not prove the release itself is authentic. Authenticity comes from the signed attestations below (build provenance / SBOM), which bind the downloaded bytes to a workflow identity.

# Download one archive and its checksum from the release
gh release download v0.1.44 -R d-o-hub/rust-self-learning-memory \
  -p 'do-memory-cli-x86_64-unknown-linux-gnu.tar.xz*'

# Verify (prints "...tar.xz: OK" on success)
sha256sum -c do-memory-cli-x86_64-unknown-linux-gnu.tar.xz.sha256

The same files can be fetched with plain curl:

BASE=https://github.com/d-o-hub/rust-self-learning-memory/releases/download/v0.1.44
curl -LO "$BASE/do-memory-cli-x86_64-unknown-linux-gnu.tar.xz"
curl -LO "$BASE/do-memory-cli-x86_64-unknown-linux-gnu.tar.xz.sha256"
sha256sum -c do-memory-cli-x86_64-unknown-linux-gnu.tar.xz.sha256

Optionally download every archive and verify them all at once against the combined manifest:

sha256sum -c sha256.sum

On macOS, sha256sum is not installed by default; use shasum -a 256 -c with the same file.

Verify build provenance

Archives built by the release workflow carry a SLSA build-provenance attestation signed through Sigstore. Verify it with the GitHub CLI, pinning the signer workflow so only .github/workflows/release.yml (not any other workflow in the repository) can satisfy the check:

gh attestation verify do-memory-cli-x86_64-unknown-linux-gnu.tar.xz \
  -R d-o-hub/rust-self-learning-memory \
  --signer-workflow d-o-hub/rust-self-learning-memory/.github/workflows/release.yml

Substitute the tag you downloaded to also pin the source ref:

gh attestation verify do-memory-cli-x86_64-unknown-linux-gnu.tar.xz \
  -R d-o-hub/rust-self-learning-memory \
  --signer-workflow d-o-hub/rust-self-learning-memory/.github/workflows/release.yml \
  --source-ref refs/tags/vX.Y.Z

This enforces the default https://slsa.dev/provenance/v1 predicate and binds the archive to a build performed by that workflow. Run it on the downloaded file whose digest you hold — the whole point is to bind the bytes you actually have to a signed claim about their origin.

Requirements. The gh attestation command needs GitHub CLI 2.49.0 or newer:

gh --version    # e.g. gh version 2.49.0

See the GitHub CLI manual for gh attestation verify for the full flag set (--signer-workflow, --format json, offline bundles, …).

Verify an SBOM attestation

CycloneDX SBOMs are attested with the CycloneDX predicate type. Pass it explicitly with --predicate-type:

gh attestation verify do-memory-cli-x86_64-unknown-linux-gnu.tar.xz \
  -R d-o-hub/rust-self-learning-memory \
  --signer-workflow d-o-hub/rust-self-learning-memory/.github/workflows/release.yml \
  --predicate-type https://cyclonedx.org/bom

To inspect the attested SBOM itself, add JSON output:

gh attestation verify do-memory-cli-x86_64-unknown-linux-gnu.tar.xz \
  -R d-o-hub/rust-self-learning-memory \
  --signer-workflow d-o-hub/rust-self-learning-memory/.github/workflows/release.yml \
  --predicate-type https://cyclonedx.org/bom \
  --format json \
  --jq '.[].verificationResult.statement.predicate'

https://cyclonedx.org/bom is the predicate type CycloneDX defines for its bill-of-material flavours; see the CycloneDX specification overview.

Verify an immutable release

When repository immutability is enabled, GitHub generates a signed release attestation binding the tag, commit, and assets. Verify it with the -R flag (consumers rarely run this from a clone):

gh release verify vX.Y.Z -R d-o-hub/rust-self-learning-memory

Use gh release verify-asset to check that a local file exactly matches a published release asset:

gh release verify-asset vX.Y.Z <path-to-downloaded-archive> \
  -R d-o-hub/rust-self-learning-memory

Note: gh release verify only proves something once repository immutability is enabled for the repository (a repository setting). Until then, releases are not locked and no release attestation is generated — the command fails for releases published before that. The command needs GitHub CLI 2.81.0 or newer.

See Immutable releases and Verifying the integrity of a release.

If verification fails

• Do not use a release whose checksum or attestation does not verify. Delete the downloaded files rather than running them.
• Re-download from https://github.com/d-o-hub/rust-self-learning-memory/releases — a corrupted download is the most common cause of a checksum mismatch.
• If the checksum is consistently wrong, or gh attestation verify / gh release verify fails against a fresh download, treat it as a supply-chain incident and report it through the process in SECURITY.md (a private security advisory — do not open a public issue).

References

• Artifact attestations
• Using artifact attestations to establish provenance
• Verifying the integrity of a release
• Immutable releases
• gh attestation verify
• gh release verify