Metadata-Version: 2.4
Name: cdms
Version: 0.1.0
Summary: Contextual Differentiation Memory Service — a local-first, forgetting-driven memory daemon for Claude Code CLI
Project-URL: Homepage, https://github.com/Chance6706/contextual_differentiation_memory_service
Project-URL: Repository, https://github.com/Chance6706/contextual_differentiation_memory_service
Project-URL: Issues, https://github.com/Chance6706/contextual_differentiation_memory_service/issues
Project-URL: Documentation, https://github.com/Chance6706/contextual_differentiation_memory_service#readme
Author: Josh Nissen
License: MIT
Keywords: agent,claude-code,consolidation,forgetting,individuation,mcp,memory,sqlite-vec
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.10
Requires-Dist: fastembed<1.0,>=0.4.0
Requires-Dist: mcp<2,>=1.28
Requires-Dist: numpy<3,>=1.26
Requires-Dist: sqlite-vec<0.2,>=0.1.9
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: render
Requires-Dist: httpx>=0.27; extra == 'render'
Description-Content-Type: text/markdown

# CDMS &mdash; Contextual Differentiation Memory Service

> *An AI that grows a personality by forgetting.*

[![PyPI](https://img.shields.io/pypi/v/cdms)](https://pypi.org/project/cdms/)
[![Python](https://img.shields.io/pypi/pyversions/cdms)](https://pypi.org/project/cdms/)
[![License](https://img.shields.io/pypi/l/cdms)](https://github.com/Chance6706/contextual_differentiation_memory_service/blob/main/LICENSE)

CDMS is a local-first, forgetting-driven memory daemon for AI agents. Most memory systems accumulate everything. CDMS does the opposite: it captures each turn, scores it for salience, lets noise decay away, and consolidates survivors during idle periods into a compact personality. Two instances fed different histories develop measurably different recall patterns.

Runs entirely on your machine (0 GPU, single SQLite file). Integrates with Claude Code via lifecycle hooks and an MCP server.

---

## Quickstart

```bash
# 1. Install
pip install cdms

# 2. Initialize
cdms init --scope user

# 3. Verify
cdms doctor

# 4. Restart Claude Code and approve the 'cdms-memory' MCP server
```

That's it. CDMS captures your sessions and builds memory automatically.

**Check that it's working:**
```bash
cdms stats                       # see what's been captured
cdms retrieve "build"            # query memory
cdms history                     # recent timeline
```

**Project-scoped memory:**
```bash
cdms init --scope project        # per-repo store instead of global
```

**Uninstall anytime:**
```bash
cdms uninstall --scope user --purge
```

---

## What CDMS Does

Most AI agents treat memory as a bucket: add everything, query everything. That works for personalization, but it doesn't create a *personality* — it creates a database with your name on it.

CDMS applies a cheap "is this worth keeping?" rule to everything an AI does, lets the rest decay, and consolidates the survivors into a compact sense of self. Feed two CDMS instances the same conversations but with different forgetting policies, and they develop measurably different recall patterns. The differences are what make them distinct.

**Observed so far:** seeded with ~10k real coding-session turns across three projects, CDMS grew three distinct personalities with zero overlap in their defining traits.

---

## Why CDMS?

Other memory systems accumulate. CDMS discriminates.

| | CDMS | Mem0 | Zep / Graphiti | Letta |
|---|---|---|---|---|
| **Core approach** | Forgetting-driven | ADD-only accumulation | Temporal knowledge graph | Context window management |
| **Creates distinct personalities?** | Yes — two instances diverge | No — remembers facts about users | No — tracks entity relationships | Partially — LLM-written persona |
| **Runs fully local** | Yes (sqlite-vec, 0 GPU) | Partial (needs cloud LLM) | No (Neo4j + cloud LLM) | Partial (DB + vector store + LLM) |
| **Forgetting** | Salience-gated power-law decay | Premium feature gate | Temporal invalidation only | Summarization |
| **Security model** | Provenance + trust boundary | API key scoping | None | Tool permissions |

- Want exhaustive recall of everything? Use Mem0.
- Want a temporal knowledge graph? Use Zep.
- Want a full agent OS? Use Letta.
- Want a lightweight daemon that develops a personality through forgetting, running entirely local? Use CDMS.

---

## Architecture

```
                         Claude Code CLI
        ┌───────────────────────┴───────────────────────┐
        │ lifecycle hooks (deterministic capture)        │ MCP stdio (model-driven)
        ▼                                                ▼
  SessionStart   PostToolUse   PreCompact/SessionEnd   store · retrieve · history
  (inject ctx)   (spool turn)  (drain + consolidate)   list_paths · create_link
        │              │              │                        │
        └──────────────┴──────┬───────┴────────────────────────┘
                              ▼
                    ┌──────────────────────┐
                    │   CDMS service        │  single `cdms` binary
                    │  ┌────────────────┐   │
                    │  │ write path     │   │  surprisal-gated S0
                    │  │ read path      │   │  hybrid recall + accessibility
                    │  │ sleep/dream    │   │  evict · compete · renorm · gist
                    │  └────────────────┘   │
                    └──────────┬───────────┘
                               ▼
        SQLite (WAL) + sqlite-vec (cosine KNN) + FTS5 (BM25)   ·   CPU ONNX embedder
                    ~/.local_memory/cdms-a/memory.db              (fastembed, 0 VRAM)
```

### Three-tier memory model

```
  L1  mem_episodic   raw turn-by-turn logs          high decay   (hippocampal trace)
        │
        │  ── "sleep" consolidation ──►
        ▼
  L2  mem_gist       PersonaTree relational tuples   slow decay  (cortical gist)
        │
  L3  mem_scars      pinned crisis-remediation rules   no decay  (engineering pin)
```

### Core cognitive formulas

**Write-time salience (S0):**
```
S0 = G_goal · (S_surprise + C_contingency + W_self-ref + A_affect)
```

**Decay-driven accessibility:**
```
A(m,t) = S0 · (1 + t/τ)^(-β) · min(α^c, Cap)
```
Power-law forgetting with retrieval reinforcement, capped. 29-day half-life.

**Sleep consolidation** (runs at rest boundaries):
1. Scar elevation — negative crises pinned to L3
2. Temporal eviction — decayed episodes dropped
3. Hierarchical competition — session/epoch softmax
4. Conserved-budget renorm — zero-sum downscaling (SHY-style)
5. Mechanical tuple extraction — geometry + lexicon only; LLM never authors identity

---

## What We've Found

CDMS is a research project as much as a tool. Headline results:

- **Differentiation is real.** Three real projects (~10k turns) → three distinct psyches, zero trait overlap, stable across 6 consolidation windows. Decay is activity-based — a project you don't touch doesn't lose its personality.

- **Memory steers recall, not disposition.** Injected memory reliably steers recall on every model of a 5-model panel. But two opposite temperaments produce overlapping choices — disposition appears to live in the model's weights, not in retrievable context.

- **Enriched phenotype works.** Gist exemplars + flashbulb floor raised behavioral adherence 1.67→3.67 and rule-citation 9×, for bounded preamble cost.

Full research with methodology and caveats: [`docs/`](docs).

---

## Claude Code Integration

CDMS hooks into Claude Code two ways:

**1. Lifecycle hooks** (registered in `.claude/settings.json`):

| Hook | Action |
|---|---|
| `SessionStart` | Injects guardrails + PersonaTree as read-only context |
| `UserPromptSubmit` | Spools user intent |
| `PostToolUse` | Spools tool trajectory + outcome (~100ms) |
| `PreCompact` | Drains spool + ingests before compaction |
| `SessionEnd` | Drains, ingests, runs full consolidation |

**2. MCP stdio server** (5 tools): `store`, `retrieve`, `history`, `list_paths`, `create_link`.

---

## CLI Reference

```
cdms init                initialize store + optionally wire into Claude Code
cdms serve               run the MCP stdio server
cdms hook <Event>        handle a lifecycle hook (reads JSON on stdin)
cdms consolidate         drain queue + run sleep/dream pass
cdms drain               ingest spooled events without consolidating
cdms retrieve <q> [-k]   query memory from terminal
cdms history [-n]        recent episodic timeline
cdms paths               show PersonaTree paths
cdms stats               store statistics
cdms doctor              verify environment + warm embedder
cdms install/uninstall   wire/unwire into Claude Code
cdms forget ...          delete by --project / --session / --id
cdms ingest ...          manually ingest a turn (testing)
```

---

## Configuration

All parameters in `cdms/config.py`, overridable via `CDMS_*` env vars or `$CDMS_HOME/config.json`.

| Variable | Default | Meaning |
|---|---|---|
| `CDMS_HOME` | `~/.local_memory/cdms-a` | Data directory |
| `CDMS_EMBED_MODEL` | `BAAI/bge-small-en-v1.5` | CPU ONNX embedding model |
| `CDMS_DECAY_HALFLIFE_DAYS` | `29` | Forgetting-curve half-life |
| `CDMS_SALIENCE_BUDGET` | `1000` | Conserved global salience K |
| `CDMS_RETENTION_FLOOR` | `0.10` | Eviction threshold |
| `CDMS_CRISIS_THRESHOLD` | `3.0` | S0 bar for scar elevation |
| `CDMS_RECALL_EXEMPLARS` | `true` | Attach e.g. quotes to gists |
| `CDMS_ENFORCE_PROVENANCE` | `true` | Block untrusted content from identity |

Full reference: [`docs/PARAMETER_BASIS.md`](docs/PARAMETER_BASIS.md).

---

## Privacy, Durability & Hardening

10 adversarial red-team cycles. Key guarantees:

- **Right-to-forget** — `cdms forget` deletes across all tiers, scrubs spool, `secure_delete`
- **Secret redaction** — credentials scrubbed before persistence
- **Trust boundary** — untrusted content can never poison identity layer
- **Crash-safe** — WAL + cross-process lock + orphan reclaim + corrupt-DB quarantine
- **Embedder integrity** — vector-space identity pinned, refused on mismatch
- **Operator-only observability** — audit UI on localhost, model never sees disposition

Full report: [`docs/REDTEAM_FINDINGS.md`](docs/REDTEAM_FINDINGS.md).

---

## Development

```bash
git clone https://github.com/Chance6706/contextual_differentiation_memory_service.git
cd contextual_differentiation_memory_service
uv pip install -e ".[dev]"
CDMS_EMBED_BACKEND=hash uv run pytest -q    # 229 tests, fully offline
```

The cognitive core (`salience.py`) is pure stdlib, fully unit-tested. Tests use a deterministic hash embedder for offline runs.

---

## License

MIT