smalltalk-cli 4.0.0

Institutional memory for AI agents. Structured decisions, contradiction detection, per-response drift prevention, and a compounding PAG loop. 25 MCP tools. Zero infrastructure.

The intelligence layer for AI agents.

Structured memory that loads, guides, compounds — and never degrades.

---

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

---

Install

pip install smalltalk-cli

# 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:

# 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

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):

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:

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.

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

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:

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.

# 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.

# 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:

# 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:

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.

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

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

# 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

---

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 — 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 by @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.