dev

Author: gitctrlx

.github/workflows/cd.yml

@@ -0,0 +1,16 @@
+name: CD
+
+on:
+  push:
+    tags: ["v*.*.*"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  call-cd:
+    uses: qntx/workflows/.github/workflows/rust-cd.yml@main
+    with:
+      bin: meme
+      package: meme-cli

Cargo.lock

@@ -4,7 +4,7 @@ default-members = ["meme"]
 resolver = "3"
 
 [workspace.package]
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/qntx/meme"

Cargo.toml

@@ -1,6 +1,166 @@
 # meme
 
-Long term memory for AI agents.
+[![CI][ci-badge]][ci-url]
+[![License][license-badge]][license-url]
+[![Rust][rust-badge]][rust-url]
+
+[ci-badge]: https://github.com/qntx/meme/actions/workflows/rust.yml/badge.svg
+[ci-url]: https://github.com/qntx/meme/actions/workflows/rust.yml
+[license-badge]: https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg
+[license-url]: LICENSE-MIT
+[rust-badge]: https://img.shields.io/badge/rust-edition%202024-orange.svg
+[rust-url]: https://doc.rust-lang.org/edition-guide/
+
+**High-performance long-term memory for AI agents — three-stage pipeline with semantic compression, hybrid retrieval, and cross-session persistence, written in Rust.**
+
+meme implements the [SimpleMem](3rdparty/SimpleMem/) three-stage memory pipeline with a production-grade Rust core: (1) **Semantic Structured Compression** extracts lossless, disambiguated memory entries from dialogues via LLM, (2) **Online Semantic Synthesis** deduplicates at write time, and (3) **Intent-Aware Retrieval Planning** combines semantic, lexical (FTS), and structured metadata search with LLM-driven reflection. A full cross-session system persists memory across independent conversations.
+
+## Crates
+
+| Crate | | Description |
+| --- | --- | --- |
+| **[`meme`](meme/)** | [![crates.io][meme-crate]][meme-crate-url] [![docs.rs][meme-doc]][meme-doc-url] | Core library — pipeline, vector store, cross-session orchestrator |
+| **[`meme-cli`](meme-cli/)** | [![crates.io][cli-crate]][cli-crate-url] | CLI tool — add dialogues, ask questions, manage sessions |
+
+[meme-crate]: https://img.shields.io/crates/v/meme.svg
+[meme-crate-url]: https://crates.io/crates/meme
+[meme-doc]: https://img.shields.io/docsrs/meme.svg
+[meme-doc-url]: https://docs.rs/meme
+[cli-crate]: https://img.shields.io/crates/v/meme-cli.svg
+[cli-crate-url]: https://crates.io/crates/meme-cli
+
+## Quick Start
+
+### Install the CLI
+
+**Shell** (macOS / Linux):
+
+```sh
+curl -fsSL https://sh.qntx.fun/meme | sh
+```
+
+**PowerShell** (Windows):
+
+```powershell
+irm https://sh.qntx.fun/meme/ps | iex
+```
+
+### CLI
+
+```bash
+# Initialize configuration
+meme init
+
+# Add dialogues
+meme add -s Alice "I'll be in Tokyo next Monday for the conference."
+meme add -s Bob "Let's meet at Shibuya station at 3pm."
+
+# Import from JSONL file
+meme add --file conversation.jsonl
+
+# Ask questions
+meme ask "Where will Alice and Bob meet?"
+
+# List stored memories
+meme list
+meme list --json
+
+# Cross-session memory
+meme session start conv-001 -m "Refactor the auth module"
+meme session stop <session-id>
+meme session list
+
+# Memory consolidation (decay/merge/prune)
+meme consolidate
+
+# Export / import
+meme export -o memories.json
+```
+
+### Library
+
+```rust
+use meme::MemeBuilder;
+
+let meme = MemeBuilder::new()
+    .api_key("sk-...")
+    .model("gpt-4.1-mini")
+    .build()
+    .await?;
+
+// Add dialogues — automatically extracted into structured memory entries.
+meme.add_dialogue("Alice", "Let's meet at 2pm tomorrow", None).await?;
+meme.add_dialogue("Bob", "Sure, I'll bring the Q3 report", None).await?;
+meme.finalize().await?;
+
+// Ask questions — hybrid retrieval + LLM answer generation.
+let answer = meme.ask("When will Alice meet?").await?;
+```
+
+See [`examples/`](meme/examples/) for more: [basic](meme/examples/basic.rs), [cross-session](meme/examples/cross_session.rs), [batch import](meme/examples/batch_import.rs).
+
+## Architecture
+
+```text
+Dialogues ──► MemoryBuilder ──► VectorStore (LanceDB)
+               (Stage 1+2)         │
+                                   ├─ Semantic search (dense vectors)
+Query ──► HybridRetriever ────────►├─ Keyword search (FTS / Tantivy)
+           (Stage 3)               ├─ Structured search (metadata filters)
+               │                   │
+               ▼                   │
+          LLM Planning ◄───────────┘
+           + Reflection
+               │
+               ▼
+          Answer Generation
+```
+
+- **`meme`** — Core library. `Meme` facade wraps the three-stage pipeline behind `add_dialogue()` / `ask()`. `VectorStore` uses LanceDB for embedded vector + FTS indexing. `Embedder` supports API and local ONNX backends via enum dispatch (zero-cost). `LlmClient` is an OpenAI-compatible HTTP client with retry + exponential backoff.
+- **`meme-cli`** — Interactive CLI. TOML + env var configuration, JSONL import, table/JSON output, cross-session management.
+- **Cross-session** — `CrossOrchestrator` manages session lifecycle (start → record events → stop → extract observations → inject context). SQLite stores sessions, events, observations, and summaries. Context injection fills a token-budgeted bundle at session start.
+
+## Three-Stage Pipeline
+
+### Stage 1: Semantic Structured Compression
+
+Dialogues are windowed and sent to an LLM to extract **atomic, self-contained memory entries**. Each entry contains:
+
+- **Lossless restatement** — complete sentence with no pronouns, no relative time
+- **Keywords** — for BM25-style lexical matching
+- **Structured metadata** — timestamp, location, persons, entities, topic
+
+### Stage 2: Online Semantic Synthesis
+
+Previous-window entries are passed as context during extraction to avoid duplicating information across overlapping windows.
+
+### Stage 3: Intent-Aware Retrieval Planning
+
+A single LLM call analyzes the query to produce a **unified plan** containing:
+
+- Extracted keywords, persons, entities, time expressions
+- Targeted search queries for semantic retrieval
+- Required information types for completeness assessment
+
+The plan drives parallel execution of three search views (semantic, keyword, structured), followed by optional **reflection** rounds that assess completeness and issue additional targeted queries.
+
+## Feature Flags
+
+| Feature | Description |
+| --- | --- |
+| `api-embedding` | Remote API-based embedding (enabled by default) |
+| `onnx` | Local ONNX Runtime embedding via `ort` + `tokenizers` |
+
+## Configuration
+
+Configuration is loaded from `~/.meme/config.toml` with environment variable overrides:
+
+| Env Var | Description |
+| --- | --- |
+| `MEME_LLM_API_KEY` | OpenAI-compatible API key |
+| `MEME_LLM_BASE_URL` | API base URL |
+| `MEME_LLM_MODEL` | Model name (default: `gpt-4.1-mini`) |
+| `MEME_EMBEDDING_PROVIDER` | `api` or `onnx` |
 
 ## License
 

README.md

@@ -0,0 +1,87 @@
+# CLI installer — downloads the latest release binary from GitHub.
+# Configure $Repo and $Bin below. Everything else is derived automatically.
+#
+# Environment (upper-cased $Bin prefix):
+#   <BIN>_VERSION      Override version (default: latest)
+#   <BIN>_INSTALL_DIR  Override install directory (default: %LOCALAPPDATA%\<bin>)
+
+$ErrorActionPreference = "Stop"
+$InformationPreference = "Continue"
+$Repo = "qntx/meme"
+$Bin = "meme"
+
+$BinUpper = $Bin.ToUpper()
+$VerEnv = "${BinUpper}_VERSION"
+$DirEnv = "${BinUpper}_INSTALL_DIR"
+
+function Get-TargetArch {
+    try {
+        $a = [System.Reflection.Assembly]::LoadWithPartialName("System.Runtime.InteropServices.RuntimeInformation")
+        switch ($a.GetType("System.Runtime.InteropServices.RuntimeInformation").GetProperty("OSArchitecture").GetValue($null).ToString()) {
+            "X64" { return "x86_64-pc-windows-msvc" }
+            "Arm64" { return "aarch64-pc-windows-msvc" }
+        }
+    }
+    catch {}
+    if ([Environment]::Is64BitOperatingSystem) { return "x86_64-pc-windows-msvc" }
+    throw "32-bit Windows is not supported"
+}
+
+function Get-LatestVersion {
+    $tag = (Invoke-RestMethod "https://api.github.com/repos/$Repo/releases/latest").tag_name
+    if ($tag.StartsWith("v")) { $tag = $tag.Substring(1) }
+    return $tag
+}
+
+function Add-ToUserPath($Dir) {
+    $reg = 'registry::HKEY_CURRENT_USER\Environment'
+    $current = (Get-Item -LiteralPath $reg).GetValue('Path', '', 'DoNotExpandEnvironmentNames') -split ';' -ne ''
+    if ($Dir -in $current) { return }
+
+    Set-ItemProperty -Type ExpandString -LiteralPath $reg Path ((@($Dir) + $current) -join ';')
+    # Broadcast WM_SETTINGCHANGE so Explorer picks up the new PATH
+    $k = "$Bin-" + [guid]::NewGuid().ToString()
+    [Environment]::SetEnvironmentVariable($k, "1", "User")
+    [Environment]::SetEnvironmentVariable($k, [NullString]::value, "User")
+
+    Write-Information "  Added $Dir to PATH (restart your shell to apply)"
+}
+
+try {
+    $target = Get-TargetArch
+    $envVer = [Environment]::GetEnvironmentVariable($VerEnv)
+    $envDir = [Environment]::GetEnvironmentVariable($DirEnv)
+    $ver = if ($envVer) { $envVer } else { Get-LatestVersion }
+    $dir = if ($envDir) { $envDir } else { Join-Path $env:LOCALAPPDATA $Bin }
+
+    Write-Information "Installing $Bin v$ver ($target)"
+
+    $url = "https://github.com/$Repo/releases/download/v$ver/$Bin-$ver-$target.zip"
+    $tmp = New-Item -ItemType Directory -Path (Join-Path ([IO.Path]::GetTempPath()) ([Guid]::NewGuid()))
+
+    try {
+        Invoke-WebRequest -Uri $url -OutFile "$tmp\archive.zip" -UseBasicParsing
+        Expand-Archive "$tmp\archive.zip" -DestinationPath $tmp -Force
+
+        $null = New-Item -ItemType Directory -Force -Path $dir
+        Copy-Item "$tmp\$Bin.exe" -Destination $dir -Force
+        Write-Information "  -> $(Join-Path $dir "$Bin.exe")"
+    }
+    finally {
+        Remove-Item $tmp -Recurse -Force -ErrorAction SilentlyContinue
+    }
+
+    # Add to PATH if needed
+    if ($env:GITHUB_PATH) {
+        $dir | Out-File $env:GITHUB_PATH -Encoding utf8 -Append
+    }
+    elseif (-not ($env:Path -split ';' | Where-Object { $_ -eq $dir })) {
+        Add-ToUserPath $dir
+    }
+
+    Write-Information "`n$Bin v$ver installed successfully!"
+}
+catch {
+    Write-Error $_
+    exit 1
+}