AI记忆系统

Prerequisites

• cass CLI: The episodic memory layer. Install from cass repo
• LLM API Key (optional): For AI-powered reflection. Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_GENERATIVE_AI_API_KEY

3) Build the playbook (memory onboarding)

cm onboard status --json cm onboard sample --fill-gaps --json cm onboard read /path/to/session.jsonl --template --json cm onboard mark-done /path/to/session.jsonl ```

📦 Installation

Installer Options

```bash

Installer Robustness

The installer is designed for reliability:

• No API rate limits: Uses GitHub redirect detection instead of API calls, avoiding the 60 requests/hour unauthenticated limit
• Checksum verification: Downloads .sha256 files and verifies binary integrity before installation
• Concurrent install protection: Lock file prevents multiple installers from running simultaneously
• Graceful fallbacks: If binary download fails, automatically falls back to building from source
• Cross-platform checksums: Uses sha256sum on Linux, shasum -a 256 on macOS

Verify Installation

cm --version
cm doctor --json

Initial Setup

```bash

System Commands (Setup & Diagnostics)

```bash

Install safety hooks

cm guard --install # Claude Code pre-tool hook cm guard --git # Git pre-commit hook cm guard --install --git # Both cm guard --status # Check installation status ```

🤖 Agent Quickstart (JSON)

Always use --json in agent contexts. stdout = data, stderr = diagnostics, exit 0 = success.

```bash

→ Returns complete explanation of the system and how to use it

Quick Start

```bash

Quick Start

```bash

Examples

install.sh --version v0.2.2 --verify # Specific version install.sh --system --verify # Install to /usr/local/bin (requires sudo) install.sh --from-source # Build from source (requires bun) ```

Show LLM cost and usage statistics

cm usage

Sample sessions prioritized for gap-filling

cm onboard sample --fill-gaps ```

Adjust sample size

cm onboard sample --limit 20 ```

Targeted Sampling Options

Filter sessions by various criteria to focus on specific areas:

```bash

Full options

install.sh [--version vX.Y.Z] [--dest DIR] [--system] [--easy-mode] [--verify] [--from-source] [--quiet]

Initialize (creates global config and playbook)

cm init

Initialize configuration and playbook

cm init cm init --starter typescript # With starter template cm starters # List available starters

⚙️ Configuration

Config lives at ~/.cass-memory/config.json (global) and .cass/config.json (repo).

Precedence: CLI flags > Repo config > Global config > Defaults

Security: Repo config cannot override sensitive paths (cassPath, playbookPath, diaryDir) or user-level consent settings (crossAgent, remoteCass).

Complete Configuration Reference

{
  // LLM Settings
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "budget": {
    "dailyLimit": 0.10,
    "monthlyLimit": 2.00,
    "warningThreshold": 80
  },

  // Scoring Settings
  "scoring": {
    "decayHalfLifeDays": 90,
    "harmfulMultiplier": 4,
    "minFeedbackForActive": 3,
    "minHelpfulForProven": 10,
    "maxHarmfulRatioForProven": 0.1
  },

  // Context Settings
  "maxBulletsInContext": 50,
  "maxHistoryInContext": 10,
  "sessionLookbackDays": 7,
  "minRelevanceScore": 0.1,

  // Privacy Settings
  "crossAgent": {
    "enabled": false,
    "consentGiven": false,
    "agents": [],
    "auditLog": true
  },

  // Semantic Search Settings
  "semanticSearchEnabled": false,
  "semanticWeight": 0.6,
  "embeddingModel": "Xenova/all-MiniLM-L6-v2",
  "dedupSimilarityThreshold": 0.85,

  // Paths (usually auto-detected)
  "cassPath": "cass",
  "remoteCass": {
    "enabled": false,
    "hosts": []
  },
  "playbookPath": "~/.cass-memory/playbook.yaml",
  "diaryDir": "~/.cass-memory/diary"
}

Configuration Options Explained

LLM Settings

Scoring Settings

Context Settings

Privacy Settings

Remote History (SSH)

Remote cass is opt-in and queries other machines via SSH (using your existing SSH config/keys). Remote hits are tagged with historySnippets[].origin.kind="remote" and origin.host.

Semantic Search Settings

How do I tell whether semantic search actually ran?

The cm context command emits a semanticMode field in JSON/TOON output (one of "semantic" or "keyword"). When the user asked for semantic but the runtime could not provide it, semanticError explains why:

$ cm context "optimize API latency" --json | jq '.data | {semanticMode, semanticError}'
{ "semanticMode": "semantic", "semanticError": null }

In human output, a yellow warning banner is printed whenever semantic was requested but unavailable — no more silent fallback.

Troubleshooting: "Semantic search unavailable" in the prebuilt binary

Releases ≤ v0.2.5 shipped a prebuilt binary that could not locate its bundled WASM runtime inside Bun's virtual filesystem. This was fixed in v0.2.6 (see issue #42): the onnxruntime-web WASM files are now embedded via Bun's type: "file" imports and wired up at startup. If you see ENOENT: ... /$bunfs/dist/ort-wasm-*.wasm on an older binary, upgrade:

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/cass_memory_system/main/install.sh | bash -s -- --easy-mode

Alternatively, point cass-memory at a local Ollama daemon (no WASM):

{
  "semanticSearchEnabled": true,
  "embeddingBackend": "ollama",
  "embeddingModel": "all-minilm"
}

Environment Variables

---

MCP Client Configuration

cm serve is an HTTP transport server (not stdio). Start it first, then point your MCP client at the URL.

For Claude Code (~/.config/claude/mcp.json):

{
  "mcpServers": {
    "cm": {
      "type": "url",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

For VS Code (Cline/Continue):

{
  "mcp": {
    "servers": {
      "cass-memory": {
        "type": "url",
        "url": "http://127.0.0.1:8765/"
      }
    }
  }
}

---

Self-Documenting API

cass-memory teaches agents how to use it—no external documentation required:

```bash

🛠️ CLI Reference

Quick Reference Table

2) See the minimum viable workflow

cm quickstart --json

Onboarding Workflow for Agents

Recommended protocol for AI agents doing onboarding:

```markdown

Agent Commands (Primary Workflow)

```bash

Run MCP HTTP server for agent integration (default: 127.0.0.1:8765)

cm serve

🔬 The ACE Pipeline

cass-memory implements the Agentic Context Engineering (ACE) framework with four stages:

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  GENERATOR   │ ──▶ │  REFLECTOR   │ ──▶ │  VALIDATOR   │ ──▶ │   CURATOR    │
│              │     │              │     │              │     │              │
│ Pre-task     │     │ LLM pattern  │     │ Evidence     │     │ Deterministic│
│ context      │     │ extraction   │     │ gate against │     │ delta merge  │
│ hydration    │     │ from diary   │     │ cass history │     │ (NO LLM!)    │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘

Component Responsibilities