Metadata-Version: 2.4
Name: smalltalk-cli
Version: 4.0.0
Summary: Institutional memory for AI agents. Structured decisions, contradiction detection, per-response drift prevention, and a compounding PAG loop. 25 MCP tools. Zero infrastructure.
License: MIT
Project-URL: Homepage, https://github.com/ApexAutomate/smalltalk
Project-URL: Repository, https://github.com/ApexAutomate/smalltalk
Project-URL: Issues, https://github.com/ApexAutomate/smalltalk/issues
Keywords: ai,agents,memory,context,mcp,llm,pag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: rich>=10.11.0
Requires-Dist: mcp>=1.0.0
Dynamic: license-file

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/smalltalk-dark.svg">
    <img src="docs/smalltalk-light.svg" alt="smalltalk" width="400">
  </picture>

  <h3>The intelligence layer for AI agents.</h3>

  <p><em>Structured memory that loads, guides, compounds — and never degrades.</em></p>

  <p>
    <a href="https://pypi.org/project/smalltalk-cli"><img src="https://img.shields.io/pypi/v/smalltalk-cli?color=4f46e5&label=pip" alt="PyPI"></a>
    <a href="https://pypi.org/project/smalltalk-cli"><img src="https://img.shields.io/pypi/pyversions/smalltalk-cli?color=4f46e5" alt="Python"></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-4f46e5" alt="MIT License"></a>
    <img src="https://img.shields.io/badge/MCP%20tools-25-4f46e5" alt="25 MCP tools">
    <img src="https://img.shields.io/badge/zero%20infra-plain%20files-4f46e5" alt="zero infrastructure">
  </p>

</div>

---

## The problem nobody talks about

Halfway through a chat, your AI forgets what you decided.

It starts hallucinating. It defaults back to its base training and ignores everything you established in the first few messages. You re-explain the same context. You re-state the same constraints. You correct the same mistakes.

This happens on GPT-4. It happens on Claude. It happens on every local Ollama model you've tried. And it gets worse the longer the session runs.

The industry calls this "context drift." The math is unforgiving:

```
If each response has a 5% chance of ignoring your established context:
  After 5  responses  →  77% aligned
  After 14 responses  →  49% aligned   ← you're below 50%
  After 30 responses  →  21% aligned   ← the model has effectively forgotten you
```

**This is not a model intelligence problem. It's an architecture problem.**

The model was never given a reliable, machine-readable source of truth about your world. It's improvising from conversational context that it's also gradually forgetting.

And the people billing you per token have no incentive to fix it — shorter context means more API calls means more revenue.

---

## What Smalltalk does

Smalltalk is the context layer that sits between your knowledge and your AI agent. It gives every model — frontier or local — a structured, contradiction-free, compounding brain that persists across every session.

```
open session   →  agent loads your decisions, rules, patterns, and habits (~2,000 tokens)
during session →  agent navigates your knowledge, routes by capability, self-corrects on drift
before risky   →  contradiction detection runs before any deploy or merge
close session  →  agent writes back what it learned, brain grows smarter
next session   →  starts further ahead than the last
```

No vector database. No RAG pipeline. No cloud infrastructure. Plain `.st` files, git-tracked, 25 MCP tools, works on any model including local Ollama.

> Anthropic recently shipped "Auto Dream" — their version of automated memory consolidation for Claude.ai. Same architectural insight. Locked to their platform, their cloud, their model. Smalltalk does the same thing on any model, on your machine, in files you own and can inspect. That's not coincidence — it's validation.

---

## The format

Every fact in your brain compresses to one line — typed, pipe-delimited, causal.

```
DECISION: deploy    | railway>vercel      | scale+cost        | 2026-04
RULE:     brand     | no-purple-gradient  | hard
PATTERN:  jwt       | broke:auth          | cause:missing-exp | fix:add-exp-claim | reuse:y
HABIT:    think     | trigger:new-feature | enforce:hard      | plan-before-code
MODELMAP: code      | qwen2.5-coder:14b   | ollama            | ctx:8192
BACKEND:  ollama    | api:localhost:11434 | ctx:4096          | tier:beginner
SKILL:    seo       | when:any-web-build  | stack:schema+meta
WIN:      palace    | score-wing-room     | 34pct-boost       | repeat:y
LINK:     kai       | rel:works-on        | nova              | valid_from:2026-03
```

Any LLM reads this natively — no fine-tuning, no special API, no decoder. A 200-line skill file becomes 20 lines. A full `_brain/` compresses from ~40,000 tokens to ~2,000.

Full grammar → [`spec/grammar.md`](spec/grammar.md)

---

## Install

```bash
pip install smalltalk-cli
```

```bash
# Claude Code
claude mcp add smalltalk -- "python -m smalltalk.mcp_server"

# Cursor / Windsurf / Codex
# {"smalltalk": {"command": "python", "args": ["-m", "smalltalk.mcp_server"]}}
```

> **Windows / PowerShell:** `-- "python -m smalltalk.mcp_server"` (quoted)

Bootstrap your first project in one command:

```bash
# Cloud API
smalltalk bootstrap ~/Dev/my-project/_brain --api-key YOUR_KEY

# Fully local — zero cost
smalltalk bootstrap ~/Dev/my-project/_brain \
  --base-url http://localhost:11434/v1 \
  --api-key ollama --model llama3.1
```

---

## How it works — the full loop

### 1. Session start — orient

```bash
smalltalk wake-up _brain/
```

Loads current truth only — active entries, permanent rules, enforced habits. Superseded decisions (`ended:`) are automatically excluded. This is the context block your agent starts with.

```
# Smalltalk wake-up — 6 entries

# enforced habits
HABIT: think  | trigger:new-feature | enforce:hard | plan-before-code
HABIT: hunt   | trigger:error+bug   | enforce:hard | find-root-cause-first

# current decisions
DECISION: deploy  | railway>vercel | scale   | 2026-04
DECISION: auth    | clerk>auth0    | sdk      | 2026-02
PATTERN:  jwt     | broke:auth     | cause:missing-exp | fix:add-exp-claim | reuse:y
WIN:      palace  | score-wing-room | 34pct-boost | repeat:y
```

### 2. During the session — navigate, route, reinforce

The agent navigates your knowledge structure (not keyword search):

```bash
smalltalk navigate _brain/ "auth decisions"
# → _brain/decisions.st     (score: high, hall: DECISION)
# → _brain/projects/auth.st (score: medium)

smalltalk route skills/ "build a landing page"
# → ui-designer.st  (SKILL: landing-page+demo-build, score: 9)
# → seo-expert.st   (USE when: any-web-build, score: 7)
```

Mid-session drift prevention — runs every N responses, no-op otherwise:

```bash
smalltalk reinforce _brain/
# → injects compact brain reminder when response count hits threshold
# → empty return if not yet due (safe to call on every response)
```

Wire it automatically in your `CLAUDE.md` / system prompt:

```
TRIGGER: every-response | event:response-complete | then:smalltalk_reinforce
```

### 3. Before risky actions — check

Rules-based contradiction detection. No LLM required. Runs in milliseconds.

```bash
smalltalk check _brain/
```

```
[CONFLICT] Found 1 contradiction(s)  (0 CRITICAL, 1 WARNING)

  1. [WARNING] DECISION: deploy | diverging-choices
     decisions.st:3  DECISION: deploy | vercel>railway | cost | 2026-01  << older
     decisions.st:7  DECISION: deploy | railway>vercel | scale | 2026-04  << newer

     Resolution: smalltalk kg invalidate _brain/decisions.st 3
```

When an agent reads contradictory facts, it picks one arbitrarily. Smalltalk catches this before the agent acts.

### 4. Session end — close the loop

```bash
smalltalk session-end _brain/ \
  --summary "Chose Clerk over Auth0 — SDK simplicity won. JWT was breaking on missing exp claim. Palace scoring gave 34% retrieval improvement."
```

The LLM extracts structured entries, writes them to the brain, checks for contradictions. One command. The brain compounds.

Or wire it automatically:

```
TRIGGER: session-end | event:task-complete | then:smalltalk_session_end
```

### 5. Drift detection — per response

Catch when the model drifted from encoded decisions before it compounds:

```bash
smalltalk eval _brain/ \
  --task "build the hero section" \
  --expected "follow design system — purple gradient, Inter font, mobile-first" \
  --actual "agent used blue, added inline styles, ignored breakpoints"
```

When drift is detected: writes a corrective `PATTERN` + `RULE` to the brain immediately, returns a reinforce block for injection. The correction is permanent — it won't happen again next session.

---

## The compounding effect

```
Session 1:   agent re-explains your stack, your style, your decisions
Session 5:   agent starts with 20 patterns from previous mistakes
Session 20:  agent starts with your full domain history — decisions, wins, what broke and why
Session 50:  agent operates like a senior engineer who's worked your codebase for years
```

Every session that closes properly leaves the brain smarter than before. Mistakes get encoded. Wins get encoded. Drift gets caught and corrected. The brain never degrades — contradictions are resolved explicitly, stale facts are `ended:`.

---

## Active Orchestration (Local Models)

The assumption that complex work requires frontier models has one root cause: unoriented models burn intelligence reconstructing your world from scratch every session. Furthermore, local 4B/7B models silently hit context limits (~4K tokens), aggressively truncating memory mid-task. 

**Smalltalk v4.0 solves this with an active Orchestrator engine.** It wraps around the LLM, breaks tasks down, and manages token budgets. When the context fills up, Smalltalk forcibly extracts a hand-off summary via the LLM, logs a `DECISION` entry to the brain, and systematically resets the context. The model never realizes its memory wiped—allowing infinite-length execution on heavily constrained hardware.

```bash
# Decompose and execute an entire task using local model constraints
smalltalk orchestrate _brain "build a login system" --task-type code

# Resume an interrupted or crashed execution exactly where it left off
smalltalk orchestrate _brain "build a login system" --resume
```

Give a 7B or 14B model a properly structured brain + orchestration, and the gap with frontier models closes.

```bash
# Detect what inference backend you're running
smalltalk detect-backends

# Full local stack — zero API cost
smalltalk bootstrap _brain/ \
  --base-url http://localhost:11434/v1 \
  --api-key ollama --model llama3.1
```

```
+ Ollama (port 11434)       tier:beginner    ctx:4096    [RUNNING]
- llama.cpp (port 8080)     tier:standard    ctx:32000   [not found]
- ik_llama (port 8081)      tier:performance ctx:128000  [not found]
- bitnet.cpp (port 8082)    tier:cpu-native  ctx:128000  [not found]

WARNING: Only Ollama detected.
Context cap: Ollama silently caps context at ~4096 on consumer hardware.
Upgrade: build llama.cpp for full context support.
```

Contradiction detection never requires a model — always local, always free.

A well-oriented local 14B competes with a disoriented frontier model on your domain.

---

## Causal intake — learn from anything

Convert articles, Reddit threads, research papers, and documentation into structured brain entries — capturing not just rules, but the evidence and reasoning behind them:

```bash
# Standard conversion
smalltalk mine _brain/ --api-key YOUR_KEY

# Causal mode — extracts WHY, evidence, source, and contradictions
smalltalk mine _brain/ --api-key YOUR_KEY --causal
```

Or feed raw text directly via MCP:

```python
smalltalk_intake(content="<article text>", brain_dir="_brain/")
# → extracts DECISION/PATTERN/RULE/HABIT entries with evidence:cited | source:article
```

---

## REST API Server

Smalltalk now ships with a full standard-library REST API for seamless integration with automation platforms like **n8n** and **EvoNexus**, or custom frontend environments without MCP support.

```bash
smalltalk serve _brain/ --port 8765
```

Wire into EvoNexus or other agent wrappers via standard HTTP requests to achieve automated context reinforcement:
```
TRIGGER: every-response | then:POST http://localhost:8765/reinforce
```

---

## MCP server — 25 tools

```bash
python -m smalltalk.mcp_server
```

| Category | Tool | Purpose |
|---|---|---|
| **Orientation** | `smalltalk_wake_up` | Session start — load brain context |
| | `smalltalk_bootstrap_info` | Bootstrap protocol for new projects |
| **Navigation** | `smalltalk_navigate` | Find relevant files by domain |
| | `smalltalk_route` | Match task to skill files |
| | `smalltalk_list_wings` | List palace wings |
| | `smalltalk_list_rooms` | Rooms in a wing |
| **Drift prevention** | `smalltalk_reinforce` | Mid-session brain re-injection |
| | `smalltalk_eval` | Per-response drift detection |
| | `smalltalk_session_end` | Automated closing ritual |
| **Contradiction** | `smalltalk_check` | Detect contradictions (no LLM) |
| | `smalltalk_kg_invalidate` | Resolve — writes `ended:` |
| **Knowledge graph** | `smalltalk_kg_query` | Entity relationships |
| | `smalltalk_kg_timeline` | Chronological entity history |
| | `smalltalk_kg_visualize` | Interactive graph (HTML) |
| **Memory** | `smalltalk_diary_write` | Write to agent diary |
| | `smalltalk_diary_read` | Read accumulated expertise |
| | `smalltalk_intake` | Causal text-to-brain intake |
| **Infrastructure** | `smalltalk_detect_backends` | Scan local inference backends |
| **Files** | `smalltalk_search` | Keyword search across .st files |
| | `smalltalk_status` | File/entry count breakdown |
| | `smalltalk_get_spec` | Full grammar reference |
| | `smalltalk_list_files` | All .st files with counts |
| | `smalltalk_read_file` | Read a .st file |
| | `smalltalk_palace_init` | Index directory for navigation |
| | `smalltalk_palace_index` | Refresh index |

---

## The numbers

| | Without Smalltalk | With Smalltalk |
|---|---|---|
| Session start | agent starts blank | agent starts oriented |
| Context drift | compounds every response | caught and corrected automatically |
| Contradictions | agent picks one arbitrarily | detected before the agent acts |
| Brain compounds | no — every session resets | yes — every session writes back |
| One skill file | ~1,800 tokens | ~180 tokens (90% compression) |
| Full `_brain/` | ~20,000–50,000 tokens | ~2,000–5,000 tokens |
| Local 7B/14B on domain work | unreliable | competitive with frontier |
| Infrastructure required | no (RAG does) | no — plain files, git-tracked |

---

## CLI reference

```bash
# Bootstrap
smalltalk bootstrap <dir> --api-key <key>
smalltalk bootstrap <dir> --base-url http://localhost:11434/v1 --api-key ollama

# Session cycle
smalltalk wake-up <dir>                      # start: load orientation
smalltalk navigate <dir> "<query>"           # during: find relevant files
smalltalk route <dir> "<task>"               # during: match task to skills
smalltalk reinforce <dir>                    # during: prevent drift (every N responses)
smalltalk check <dir>                        # before risky: contradiction check
smalltalk eval <dir> -t "<task>" -e "<expected>" -a "<actual>"   # evaluate response
smalltalk session-end <dir> -s "<summary>"  # end: automated closing ritual
smalltalk diary write <id> "<entry>"         # end: manual diary write
smalltalk diary read <id>                    # end: review logs

# Causal intake
smalltalk mine <dir> --api-key <key>         # convert .md to .st
smalltalk mine <dir> --api-key <key> --causal  # extract evidence chains
smalltalk mine <dir> --watch                 # auto-convert on save

# Knowledge graph
smalltalk kg query <dir> <entity>
smalltalk kg timeline <dir> <entity>
smalltalk kg invalidate <file> <line>
smalltalk kg visualize <dir>

# Palace navigation
smalltalk palace init <dir>
smalltalk palace index <dir>

# Orchestration & Server
smalltalk orchestrate <dir> "<task>"         # run structured multi-step task
smalltalk orchestrate <dir> "<task>" --resume # resume a crashed run
smalltalk serve <dir> --port 8765            # run REST API

# Hardware
smalltalk detect-backends
smalltalk detect-backends --brain <dir>      # write BACKEND entries to brain

# Utilities
smalltalk init <dir>         # scan — see what's convertible
smalltalk status <dir>       # conversion progress
smalltalk install-hook <dir> # auto-convert on git commit
```

Setup for Claude Code, Cursor, Windsurf, Codex, Antigravity → [docs/setup.md](docs/setup.md)

---

## Requirements

- Python 3.9+
- `typer`, `httpx`, `rich`, `mcp` — installed automatically
- API key only needed for `mine` and `session-end`. All detection, navigation, and contradiction checking is local and free.

---

## Credits

**[MemPalace](https://github.com/MemPalace/mempalace)** — Smalltalk evolves the AAAK dialect from MemPalace, which proved that LLMs read structured compressed text natively. MemPalace introduced the Palace metaphor for agent memory navigation.

**[Waza](https://github.com/tw93/Waza)** by [@tw93](https://github.com/tw93) — 8 engineering habits from 500+ real sessions. `examples/waza-habits.st` brings these habits to any model, any platform. MIT licensed.

---

## License

MIT

---

*Smalltalk v4.0.0 — the intelligence layer for AI agents.*
