titans-disposition

# TITANS Disposition

<p align="center">
  <img src="assets/banner.png" alt="TITANS Disposition" width="100%">
</p>

**Persistent memory + self-improvement for AI coding agents.**

Your AI agents don't learn. Ours do. Here's how -- and the [math proving why](docs/research/INVERSE_REWARD_DESIGN.md) your current approach makes them worse.

```bash
pip install titans-disposition
```

---

## The Problem (Two of Them)

**Problem 1: Agents reset.** Every AI coding agent -- Claude Code, Cursor, Cursor -- starts fresh each session. Session 500 feels the same as session 1. Context injection (system prompts, RAG) addresses *knowledge*. Nothing addresses *disposition*: the accumulated sense of how to work with *you*.

**Problem 2: Naive self-improvement actively declines.** If you try to fix Problem 1 by scoring agent output and nudging weights toward deficits, you get *worse* over time. We proved this mathematically: deficit-chasing on a quality simplex with nonuniform proxy bias produces monotonic decline. The fix requires structural protocols, not continuous optimization. ([Full proof](docs/research/INVERSE_REWARD_DESIGN.md))

## Three Pillars

### 1. Disposition Engine

A gradient-gated M-vector that gives agents persistent taste.

Based on [Titans: Learning to Memorize at Test Time](https://arxiv.org/abs/2501.00663) (Google, 2025), but applied as a disposition accumulation system. Every prompt is classified, gated, and deposited into a weight matrix that evolves with your collaboration:

```python
from titans_disposition import DispositionEngine

engine = DispositionEngine(conversation_id="my-project")
engine.deposit("Add error handling to the auth module")   # routine: minimal weight
engine.deposit("No, use composition not inheritance")      # correction: punches through
engine.deposit("Redesign the pipeline as event-driven")    # architectural: carries momentum

metrics = engine.read()
print(f"M norm: {metrics['m_norm']:.4f}")  # The shape of your collaboration
```

T