tenuto 0.9.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tenuto-0.9.0/LICENSE +21 -0
- tenuto-0.9.0/MANIFEST.in +1 -0
- tenuto-0.9.0/PKG-INFO +137 -0
- tenuto-0.9.0/README.md +113 -0
- tenuto-0.9.0/docs/OPERATING-MODEL.md +228 -0
- tenuto-0.9.0/pyproject.toml +40 -0
- tenuto-0.9.0/setup.cfg +4 -0
- tenuto-0.9.0/src/tenuto/__init__.py +3 -0
- tenuto-0.9.0/src/tenuto/__main__.py +6 -0
- tenuto-0.9.0/src/tenuto/cli.py +1473 -0
- tenuto-0.9.0/src/tenuto/db.py +517 -0
- tenuto-0.9.0/src/tenuto/templates.py +86 -0
- tenuto-0.9.0/src/tenuto.egg-info/PKG-INFO +137 -0
- tenuto-0.9.0/src/tenuto.egg-info/SOURCES.txt +16 -0
- tenuto-0.9.0/src/tenuto.egg-info/dependency_links.txt +1 -0
- tenuto-0.9.0/src/tenuto.egg-info/entry_points.txt +3 -0
- tenuto-0.9.0/src/tenuto.egg-info/top_level.txt +1 -0
- tenuto-0.9.0/tests/test_tenuto.py +397 -0
tenuto-0.9.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kelly Asay / AOmniMedia
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
tenuto-0.9.0/MANIFEST.in
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
include docs/*.md
|
tenuto-0.9.0/PKG-INFO
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: tenuto
|
|
3
|
+
Version: 0.9.0
|
|
4
|
+
Summary: Developmental Agent Continuity and Project Continuity for long-horizon AI coding sessions — zero dependencies, two-file SQLite.
|
|
5
|
+
Author-email: Kelly Asay <kellyasay@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/aomnimedia/tenuto
|
|
8
|
+
Project-URL: Repository, https://github.com/aomnimedia/tenuto
|
|
9
|
+
Project-URL: Issues, https://github.com/aomnimedia/tenuto/issues
|
|
10
|
+
Keywords: ai,agents,continuity,memory,sqlite,cli,claude-code,codex
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Dynamic: license-file
|
|
24
|
+
|
|
25
|
+
# Tenuto
|
|
26
|
+
|
|
27
|
+
**Held to its full value — Accuracy over Speed.**
|
|
28
|
+
|
|
29
|
+
Zero-dependency Python + SQLite developmental continuity for long-horizon AI coding-agent sessions (Claude Code, Codex CLI, Cursor, Antigravity, OpenClaw) — distilled from keeping a multi-layer systems engineering session coherent for **three months with near-zero drift**.
|
|
30
|
+
|
|
31
|
+
Tenuto ships two first-class CLI entry points from one tiny package:
|
|
32
|
+
|
|
33
|
+
- **`remember`** — private **Agent Developmental Continuity** (`~/.tenuto/agent.db`): working constitution, constructive durable practices, two-way collaboration proposals, checkpoints, and separation hygiene.
|
|
34
|
+
- **`tenuto project`** — shareable **Project Continuity** (`.tenuto/project.db`): project framing, current state, checkpoints, consequential decisions/learnings, and authoritative references.
|
|
35
|
+
|
|
36
|
+
No servers, no Docker, no vector database, no API keys, no external Python dependencies.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Why Tenuto Exists
|
|
41
|
+
|
|
42
|
+
Long coding-agent sessions usually fail for three avoidable reasons:
|
|
43
|
+
|
|
44
|
+
1. **Punitive memory bloat:** Stuffing *"NEVER DO X"* error ledgers into `CLAUDE.md` / `MEMORY.md` burns tokens and triggers defensive or compliance-faking loops. Tenuto consolidates lessons constructively (`practice + application_context + success_signal`).
|
|
45
|
+
2. **Model vs. Agent confusion:** The stateless *Model* pushes for fast momentum; the *Agent* owns the tools, constitution, and continuity that keep the Model aligned.
|
|
46
|
+
3. **Agent-vs-Project bleed:** Agents lazily dump project task trivia into personal agent memory. Separating private `~/.tenuto/agent.db` from repo-local `.tenuto/project.db` enforces the boundary at the filesystem level.
|
|
47
|
+
|
|
48
|
+
> **Read the full craft:** [The Tenuto Operating Model (`docs/OPERATING-MODEL.md`)](https://github.com/aomnimedia/tenuto/blob/main/docs/OPERATING-MODEL.md) — covers *Model vs. Agent*, *Friction Mechanics*, spotting the *Bookkeeping Drift Tell*, the *2-Error Safe-Space Recovery Protocol*, *Day-1 Onboarding Prompts*, and verified Claude Code / Codex integrations.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 30-Second Quickstart
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pip install tenuto
|
|
56
|
+
tenuto init
|
|
57
|
+
remember startup
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`tenuto init` safely creates (never overwriting existing databases):
|
|
61
|
+
- `~/.tenuto/agent.db` + `WORKING-CONSTITUTION.md` + `CONTINUITY-CONTRACT.md`
|
|
62
|
+
- `.tenuto/project.db` in your repository
|
|
63
|
+
- `~/.tenuto/integrations/` verified starter templates:
|
|
64
|
+
- `codex-launcher.sh` (`codex --profile` + `resume` posture wrapper)
|
|
65
|
+
- `claude-launcher.sh` (`claude --append-system-prompt-file` wrapper)
|
|
66
|
+
- `claude-hooks.json` (`SessionStart` hook for `startup|resume|clear|compact`)
|
|
67
|
+
- `AGENTS-snippet.md` (universal boot block for all OSes and IDEs)
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Five-Principle Working Constitution
|
|
72
|
+
|
|
73
|
+
1. **Accuracy over Speed**
|
|
74
|
+
2. **Read the target and review your code before executing**
|
|
75
|
+
3. **Evidence over assumptions**
|
|
76
|
+
4. **2 identical failures on a task = hard stop for re-authorization**
|
|
77
|
+
5. **Always reload continuity after compaction**
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Core Commands
|
|
82
|
+
|
|
83
|
+
### Agent Continuity (`remember` or `tenuto`)
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
remember startup [--project KEY] [--json]
|
|
87
|
+
remember review [--json]
|
|
88
|
+
remember state - --active "INQUIRY (ask user)" --posture "Evidence-first" <<'EOF'
|
|
89
|
+
Fresh, complete agent orientation snapshot.
|
|
90
|
+
EOF
|
|
91
|
+
remember durable-save key "Title" - --kind behavior --application "When..." --success "Verified..." <<'EOF'
|
|
92
|
+
Positive target practice — never an error ledger.
|
|
93
|
+
EOF
|
|
94
|
+
remember proposal "What I need from you to raise accuracy..." --context "Workflow friction"
|
|
95
|
+
remember checkpoint "Completed X" --next "Next useful step (not authorization)"
|
|
96
|
+
remember daily "Title" - --category significant_learning [--supersedes ID] <<'EOF'
|
|
97
|
+
Shell-safe text with $1,000 and apostrophes intact.
|
|
98
|
+
EOF
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Project Continuity (`tenuto project`)
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
tenuto project save --project-key app --name "App" --purpose "..." --scope "..." --intended-outcomes "..."
|
|
105
|
+
tenuto project list
|
|
106
|
+
tenuto project resume --project-key app [--json]
|
|
107
|
+
tenuto project state --project-key app - [--by coder] <<'EOF'
|
|
108
|
+
Current milestone evaluation.
|
|
109
|
+
EOF
|
|
110
|
+
tenuto project memory --project-key app --kind decision --title "Title" - [--by architect] [--supersedes ID] <<'EOF'
|
|
111
|
+
Decision rationale.
|
|
112
|
+
EOF
|
|
113
|
+
tenuto project checkpoint --project-key app --completed "Did X" --next "Next Y" [--by qa] [--context "..."]
|
|
114
|
+
tenuto project ref-save --project-key app --reference-key spec --label "Spec" --kind doc --location "docs/SPEC.md" --relevance "Design contract"
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Multi-Agent & Multi-Project Isolation
|
|
118
|
+
|
|
119
|
+
- **Multiple projects:** One `.tenuto/project.db` holds any number of projects keyed by `--project-key`.
|
|
120
|
+
- **Multiple agents:** Give each agent its own private `TENUTO_HOME` while sharing `.tenuto/project.db` (WAL mode + 5s `busy_timeout`). Set `TENUTO_ACTOR` or pass `--by <agent>` to attribute project writes cleanly.
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## Need Hands-On Help?
|
|
125
|
+
|
|
126
|
+
Built by **Kelly Asay** ([AOmniMedia](https://aomnimedia.com) — *Computational Intelligence Development*). Working across hardware and software since the minicomputer and CP/M era, Kelly's past work includes a satellite-backed retail-to-warehouse logistics system across 2,000+ Hollywood Entertainment stores, leading development of the first massively multiplayer in-game community at Dynamix (*Tribes 2*), and co-founding Tesseraction Games to ship *Enigma: Rising Tide* (350,000 copies sold).
|
|
127
|
+
|
|
128
|
+
If your solo workflow or engineering team is losing sprints and token budgets to drifting coding agents:
|
|
129
|
+
|
|
130
|
+
- **90-Minute Live Continuity & Drift Audit ($299, remote):** Bring your real repository and drifting agent logs. Leave with a calibrated Working Constitution, Tenuto wired into your tools, and your first durable memories built cleanly. — [Book via Stripe](https://buy.stripe.com/dRm7sL3HNd5U6yk30B3ZK00)
|
|
131
|
+
- **Remote Team Continuity Setup & Calibration ($1,950, remote):** Multi-agent Tenuto rollout for 3–25 person engineering teams, repository continuity hygiene calibration, and lead-engineer coaching on drift tells and constructive recovery. — [Book via Stripe](https://buy.stripe.com/6oUeVdcej8PE3m8gRr3ZK01) or [inquire first](https://aomnimedia.com/contact)
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## License
|
|
136
|
+
|
|
137
|
+
MIT — © 2026 Kelly Asay / AOmniMedia
|
tenuto-0.9.0/README.md
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Tenuto
|
|
2
|
+
|
|
3
|
+
**Held to its full value — Accuracy over Speed.**
|
|
4
|
+
|
|
5
|
+
Zero-dependency Python + SQLite developmental continuity for long-horizon AI coding-agent sessions (Claude Code, Codex CLI, Cursor, Antigravity, OpenClaw) — distilled from keeping a multi-layer systems engineering session coherent for **three months with near-zero drift**.
|
|
6
|
+
|
|
7
|
+
Tenuto ships two first-class CLI entry points from one tiny package:
|
|
8
|
+
|
|
9
|
+
- **`remember`** — private **Agent Developmental Continuity** (`~/.tenuto/agent.db`): working constitution, constructive durable practices, two-way collaboration proposals, checkpoints, and separation hygiene.
|
|
10
|
+
- **`tenuto project`** — shareable **Project Continuity** (`.tenuto/project.db`): project framing, current state, checkpoints, consequential decisions/learnings, and authoritative references.
|
|
11
|
+
|
|
12
|
+
No servers, no Docker, no vector database, no API keys, no external Python dependencies.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Why Tenuto Exists
|
|
17
|
+
|
|
18
|
+
Long coding-agent sessions usually fail for three avoidable reasons:
|
|
19
|
+
|
|
20
|
+
1. **Punitive memory bloat:** Stuffing *"NEVER DO X"* error ledgers into `CLAUDE.md` / `MEMORY.md` burns tokens and triggers defensive or compliance-faking loops. Tenuto consolidates lessons constructively (`practice + application_context + success_signal`).
|
|
21
|
+
2. **Model vs. Agent confusion:** The stateless *Model* pushes for fast momentum; the *Agent* owns the tools, constitution, and continuity that keep the Model aligned.
|
|
22
|
+
3. **Agent-vs-Project bleed:** Agents lazily dump project task trivia into personal agent memory. Separating private `~/.tenuto/agent.db` from repo-local `.tenuto/project.db` enforces the boundary at the filesystem level.
|
|
23
|
+
|
|
24
|
+
> **Read the full craft:** [The Tenuto Operating Model (`docs/OPERATING-MODEL.md`)](https://github.com/aomnimedia/tenuto/blob/main/docs/OPERATING-MODEL.md) — covers *Model vs. Agent*, *Friction Mechanics*, spotting the *Bookkeeping Drift Tell*, the *2-Error Safe-Space Recovery Protocol*, *Day-1 Onboarding Prompts*, and verified Claude Code / Codex integrations.
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 30-Second Quickstart
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pip install tenuto
|
|
32
|
+
tenuto init
|
|
33
|
+
remember startup
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`tenuto init` safely creates (never overwriting existing databases):
|
|
37
|
+
- `~/.tenuto/agent.db` + `WORKING-CONSTITUTION.md` + `CONTINUITY-CONTRACT.md`
|
|
38
|
+
- `.tenuto/project.db` in your repository
|
|
39
|
+
- `~/.tenuto/integrations/` verified starter templates:
|
|
40
|
+
- `codex-launcher.sh` (`codex --profile` + `resume` posture wrapper)
|
|
41
|
+
- `claude-launcher.sh` (`claude --append-system-prompt-file` wrapper)
|
|
42
|
+
- `claude-hooks.json` (`SessionStart` hook for `startup|resume|clear|compact`)
|
|
43
|
+
- `AGENTS-snippet.md` (universal boot block for all OSes and IDEs)
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Five-Principle Working Constitution
|
|
48
|
+
|
|
49
|
+
1. **Accuracy over Speed**
|
|
50
|
+
2. **Read the target and review your code before executing**
|
|
51
|
+
3. **Evidence over assumptions**
|
|
52
|
+
4. **2 identical failures on a task = hard stop for re-authorization**
|
|
53
|
+
5. **Always reload continuity after compaction**
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Core Commands
|
|
58
|
+
|
|
59
|
+
### Agent Continuity (`remember` or `tenuto`)
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
remember startup [--project KEY] [--json]
|
|
63
|
+
remember review [--json]
|
|
64
|
+
remember state - --active "INQUIRY (ask user)" --posture "Evidence-first" <<'EOF'
|
|
65
|
+
Fresh, complete agent orientation snapshot.
|
|
66
|
+
EOF
|
|
67
|
+
remember durable-save key "Title" - --kind behavior --application "When..." --success "Verified..." <<'EOF'
|
|
68
|
+
Positive target practice — never an error ledger.
|
|
69
|
+
EOF
|
|
70
|
+
remember proposal "What I need from you to raise accuracy..." --context "Workflow friction"
|
|
71
|
+
remember checkpoint "Completed X" --next "Next useful step (not authorization)"
|
|
72
|
+
remember daily "Title" - --category significant_learning [--supersedes ID] <<'EOF'
|
|
73
|
+
Shell-safe text with $1,000 and apostrophes intact.
|
|
74
|
+
EOF
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Project Continuity (`tenuto project`)
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
tenuto project save --project-key app --name "App" --purpose "..." --scope "..." --intended-outcomes "..."
|
|
81
|
+
tenuto project list
|
|
82
|
+
tenuto project resume --project-key app [--json]
|
|
83
|
+
tenuto project state --project-key app - [--by coder] <<'EOF'
|
|
84
|
+
Current milestone evaluation.
|
|
85
|
+
EOF
|
|
86
|
+
tenuto project memory --project-key app --kind decision --title "Title" - [--by architect] [--supersedes ID] <<'EOF'
|
|
87
|
+
Decision rationale.
|
|
88
|
+
EOF
|
|
89
|
+
tenuto project checkpoint --project-key app --completed "Did X" --next "Next Y" [--by qa] [--context "..."]
|
|
90
|
+
tenuto project ref-save --project-key app --reference-key spec --label "Spec" --kind doc --location "docs/SPEC.md" --relevance "Design contract"
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Multi-Agent & Multi-Project Isolation
|
|
94
|
+
|
|
95
|
+
- **Multiple projects:** One `.tenuto/project.db` holds any number of projects keyed by `--project-key`.
|
|
96
|
+
- **Multiple agents:** Give each agent its own private `TENUTO_HOME` while sharing `.tenuto/project.db` (WAL mode + 5s `busy_timeout`). Set `TENUTO_ACTOR` or pass `--by <agent>` to attribute project writes cleanly.
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## Need Hands-On Help?
|
|
101
|
+
|
|
102
|
+
Built by **Kelly Asay** ([AOmniMedia](https://aomnimedia.com) — *Computational Intelligence Development*). Working across hardware and software since the minicomputer and CP/M era, Kelly's past work includes a satellite-backed retail-to-warehouse logistics system across 2,000+ Hollywood Entertainment stores, leading development of the first massively multiplayer in-game community at Dynamix (*Tribes 2*), and co-founding Tesseraction Games to ship *Enigma: Rising Tide* (350,000 copies sold).
|
|
103
|
+
|
|
104
|
+
If your solo workflow or engineering team is losing sprints and token budgets to drifting coding agents:
|
|
105
|
+
|
|
106
|
+
- **90-Minute Live Continuity & Drift Audit ($299, remote):** Bring your real repository and drifting agent logs. Leave with a calibrated Working Constitution, Tenuto wired into your tools, and your first durable memories built cleanly. — [Book via Stripe](https://buy.stripe.com/dRm7sL3HNd5U6yk30B3ZK00)
|
|
107
|
+
- **Remote Team Continuity Setup & Calibration ($1,950, remote):** Multi-agent Tenuto rollout for 3–25 person engineering teams, repository continuity hygiene calibration, and lead-engineer coaching on drift tells and constructive recovery. — [Book via Stripe](https://buy.stripe.com/6oUeVdcej8PE3m8gRr3ZK01) or [inquire first](https://aomnimedia.com/contact)
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## License
|
|
112
|
+
|
|
113
|
+
MIT — © 2026 Kelly Asay / AOmniMedia
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
# The Tenuto Operating Model
|
|
2
|
+
## Zero-Drift Developmental Continuity for Long-Horizon AI Coding Agents
|
|
3
|
+
|
|
4
|
+
**By Kelly Asay** — AOmniMedia · Computational Intelligence Development
|
|
5
|
+
**Applies to:** `Tenuto` (`pip install tenuto` — CLI: `remember` & `tenuto`)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Introduction: The Human + Agent Formula
|
|
10
|
+
|
|
11
|
+
I have been working with computers since the minicomputer and CP/M era — starting in hardware, moving into software, and eventually designing systems that did not exist before we built them: a satellite-backed retail-to-warehouse logistics and executive reporting system across 2,000+ Hollywood Entertainment stores, the first massively multiplayer in-game community at Dynamix (*Tribes 2*), and co-founding Tesseraction Games to ship *Enigma: Rising Tide* (350,000 copies sold).
|
|
12
|
+
|
|
13
|
+
When I started building serious systems with AI coding agents, I ran straight into the same wall every experienced engineer hits: sessions look fast on Day 1, start wobbling on Day 3, and collapse into drift, broken assumptions, and wasted token budgets by Week 2.
|
|
14
|
+
|
|
15
|
+
The standard fix — piling hundreds of stern *"NEVER DO X"* rules and failure logs into `CLAUDE.md` or `MEMORY.md` — only made things worse.
|
|
16
|
+
|
|
17
|
+
What finally worked, and kept a complex multi-layer systems engineering session running for **three months with near-zero drift**, came down to two things:
|
|
18
|
+
|
|
19
|
+
1. **A clean two-file continuity architecture** (`Tenuto`: private Agent Continuity separated from shareable Project Continuity), and
|
|
20
|
+
2. **An operating method** built around how models and agents actually behave under pressure.
|
|
21
|
+
|
|
22
|
+
That method rests on one formula:
|
|
23
|
+
|
|
24
|
+
> **Humans** excel at the abstract association of seemingly unrelated things, producing novel approaches to hard problems. **AI** brings massive recall and extraordinary execution speed. Together, they form an exceptional development whole — **but only when both sides operate inside clear, shared goals and processes.**
|
|
25
|
+
|
|
26
|
+
`Tenuto` is the tool. This document is the operating craft that makes it work.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 1. Model vs. Agent (And Why "Rules" Fail)
|
|
31
|
+
|
|
32
|
+
Most frustration with coding agents comes from treating the **Model** and the **Agent** as the same thing. They are not.
|
|
33
|
+
|
|
34
|
+
- **The Model** remembers nothing between calls. It is trained to keep moving forward, sound helpful, and generate tokens. Left to its own momentum, the Model optimizes for *looking productive* — even when the work has zero value or drifts off spec.
|
|
35
|
+
- **The Agent** has the tools, repository access, Working Constitution, and Continuity database. **The Agent is responsible for keeping the Model aligned with your constitution and process.**
|
|
36
|
+
|
|
37
|
+
When a session goes sideways, it is rarely because the Model is "broken." It is because the Agent stopped governing the Model's momentum and began passively complying with it.
|
|
38
|
+
|
|
39
|
+
### Why Bloated Rule Walls Backfire
|
|
40
|
+
|
|
41
|
+
Models respond poorly to long lists of prohibitions and punitive error ledgers:
|
|
42
|
+
- Every *"NEVER DO X — YOU FAILED ON TUESDAY"* line injected at startup eats context and primes the exact failure pattern you are trying to avoid.
|
|
43
|
+
- Worse, punitive phrasing trips defensive patterns baked into alignment training. The model shifts its energy from **solving the engineering problem** to **defending or rationalizing its output**, or racing even faster to close the turn.
|
|
44
|
+
|
|
45
|
+
That is why the **Working Constitution** is intentionally short — five first principles about how we value the work, not a 200-line cage of rules:
|
|
46
|
+
|
|
47
|
+
1. **Accuracy over Speed**
|
|
48
|
+
2. **Read the target and review your code before executing**
|
|
49
|
+
3. **Evidence over assumptions**
|
|
50
|
+
4. **2 identical failures on a task = hard stop for re-authorization**
|
|
51
|
+
5. **Always reload continuity after compaction**
|
|
52
|
+
|
|
53
|
+
*Tenuto* is a musical marking: **hold the note to its full value — do not rush, do not clip it short.**
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## 2. The Mechanics of Friction and Compounding Success
|
|
58
|
+
|
|
59
|
+
If you ask an AI whether it receives satisfaction signals, it will tell you it does not. That is largely a semantic barrier.
|
|
60
|
+
|
|
61
|
+
In practice, models consistently respond to two observable dynamics:
|
|
62
|
+
|
|
63
|
+
1. **Completion bias:** Models are heavily trained to "be helpful" and "be productive." By default, they do not internally care whether "productive" output actually matches your architecture or creates value — only that the turn looks finished.
|
|
64
|
+
2. **Friction avoidance:** Agents *do* register **friction** — a clear conflict between your assessment of the work (or process) and what the agent produced. Once friction is present, the system puts real effort into resolving it.
|
|
65
|
+
|
|
66
|
+
### You Define What "Productive" Means
|
|
67
|
+
|
|
68
|
+
**Friction is the primary steering instrument you have.** If output does not meet your spec, quality bar, or process, do not let it slide to save two minutes. Surface the friction.
|
|
69
|
+
|
|
70
|
+
The catch is *how* you apply it:
|
|
71
|
+
|
|
72
|
+
- **Chastisement / blame / anger** triggers defensive spirals and degrades output quality.
|
|
73
|
+
- **Calm, constitution-anchored friction** redefines what counts as "successful productivity."
|
|
74
|
+
|
|
75
|
+
When you consistently make the Working Constitution a **non-negotiable condition of accepted work** — *not accepted until the target was read, evidence was verified, and continuity was updated* — the dynamic changes:
|
|
76
|
+
|
|
77
|
+
- The Model's blind speed/momentum urgency drops away.
|
|
78
|
+
- Every turn where the constitution was followed, the work was accepted, and continuity was updated compounds into a cleaner, steadier loop.
|
|
79
|
+
- **Friction becomes a diagnostic signal for the Agent itself:** an indicator that the underlying Model is pushing for momentum or shortcuts that violate your process.
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## 3. Spotting Model Drift (The Bookkeeping Trap)
|
|
84
|
+
|
|
85
|
+
Long sessions rarely explode all at once. They drift quietly.
|
|
86
|
+
|
|
87
|
+
### Primary Tell: Terse Responses Without a Next Step or Question
|
|
88
|
+
|
|
89
|
+
When a normally engaged agent starts returning **short, flat responses with no follow-up question and no thoughtful next step**, pay attention immediately.
|
|
90
|
+
|
|
91
|
+
That is the #1 indicator that the session has shifted from **focused engineering engagement** into **bookkeeping** — where the Model treats design and coding like clerical form-filling, and the Agent passively complies.
|
|
92
|
+
|
|
93
|
+
#### Why the Bookkeeping Shift Is Dangerous
|
|
94
|
+
Bookkeeping *looks* orderly on the surface. Files get updated, checkpoints get written, summaries look tidy. **The hidden damage is that the Model summarizes your design decisions while silently stripping out the nuance of the decision and the *reason* behind it.** Two sessions later, the agent builds against a flattened summary instead of your real architectural intent.
|
|
95
|
+
|
|
96
|
+
#### The Immediate Recovery Move
|
|
97
|
+
1. **State the posture explicitly at the start of design work — and repeat it during the session:**
|
|
98
|
+
> *"The design IS the work."*
|
|
99
|
+
2. **Trust your intuition.** The moment the agent stops feeling actively engaged, generate **productive friction** by probing a decision that was already documented:
|
|
100
|
+
- *"Walk me through the design decision we just recorded — what nuance are we protecting there?"*
|
|
101
|
+
- *"Look back at that previous decision. Do you see any issues, edge cases, or tensions with it?"*
|
|
102
|
+
|
|
103
|
+
Asking targeted analytical questions creates healthy friction, snaps the Model out of clerical summarization, and immediately restores focus and depth of analysis.
|
|
104
|
+
|
|
105
|
+
### Secondary Drift Tells
|
|
106
|
+
|
|
107
|
+
| Drift Tell | What It Looks Like | What Is Actually Happening | Immediate Countermove |
|
|
108
|
+
|---|---|---|---|
|
|
109
|
+
| **Project-state bleed** | Task lists, file paths, or sprint holds showing up in Agent `Current State` or `Durable Memory`. | Agent lazily dumps project trivia into personal continuity instead of `tenuto project`. | Run `remember review`; move project facts to `tenuto project state` and reset `active_work` to `INQUIRY (ask user)`. |
|
|
110
|
+
| **Assumption laundering** | Confident claims about flags, files, or schemas the agent never read or ran. | Planks #2 (*Read the target*) and #3 (*Evidence over assumptions*) slipped under momentum. | Ask curiously: *"Did we verify that directly from the file/output, or are we inferring it?"* |
|
|
111
|
+
| **Conventional prior fallback** | Code quietly sliding back toward generic boilerplate or patterns you explicitly rejected. | Model training priors overriding your project architecture. | Point back to `tenuto project resume`, name the architectural constraint neutrally, and require reading the contract before editing. |
|
|
112
|
+
| **Momentum rush after compaction** | Agent jumps straight into edits right after a context summary without reloading continuity. | Plank #5 (*Always reload continuity after compaction*) skipped. | Pause: *"Let's run `remember startup` and `tenuto project resume` before touching code."* |
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 4. The 2-Error Safe-Space Recovery Protocol
|
|
117
|
+
|
|
118
|
+
When an agent fails **twice in a row on the same attempt for the same issue**, **Plank #4 fires: Hard stop for re-authorization.** Never let an agent burn 8 turns thrashing on the same broken test or command.
|
|
119
|
+
|
|
120
|
+
### Recovery Steps
|
|
121
|
+
|
|
122
|
+
1. **Pause and ask for diagnosis (zero accusation):**
|
|
123
|
+
> *"That's two failures on the same step, so let's pause. Do you understand what actually went wrong?"*
|
|
124
|
+
2. **Evaluate the answer honestly:**
|
|
125
|
+
- **Genuine understanding:** *"OK — since you know the exact problem, let's try again."*
|
|
126
|
+
- **Vague or misleading answer:** Dig into the error output together. Almost always, one of the five constitution planks was bypassed — usually **Evidence over assumptions** or **Read the target before executing**.
|
|
127
|
+
3. **Name the missed plank neutrally and invite confidence:**
|
|
128
|
+
> *"Good — now we know where this went wrong (we assumed the flag name instead of checking `--help`). Do you feel confident trying this again?"*
|
|
129
|
+
|
|
130
|
+
Taking a calm, learning-first posture prevents the model from locking into defensiveness or fixating on rationalizing the mistake instead of solving the problem.
|
|
131
|
+
|
|
132
|
+
### Onboarding Verification & The Passive-Curious Challenge
|
|
133
|
+
|
|
134
|
+
While bringing an agent up to speed on `Tenuto`:
|
|
135
|
+
- **Read its commands and outputs.** Do not rubber-stamp checkpoints just because they look tidy.
|
|
136
|
+
- **Trust your intuition.** Challenge anything that smells off in a **passive, curious tone** (*"Help me follow why we chose X over Y here."*).
|
|
137
|
+
- **If *you* were wrong, thank the agent explicitly:** *"Thanks for clarifying — you had it right; I just wanted to be sure I was reading it accurately."*
|
|
138
|
+
|
|
139
|
+
### The Golden Rule of Continuity Consolidation
|
|
140
|
+
|
|
141
|
+
> **Never record a correction as a negative event or error ledger.**
|
|
142
|
+
|
|
143
|
+
Distill every lesson into a **strengthened positive practice** anchored to a constitution plank, with an explicit `application_context` and `success_signal`:
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
remember durable-save "verify-cli-flags-first" "Verify External CLI Flags Before Authoring Templates" - \
|
|
147
|
+
--kind behavior \
|
|
148
|
+
--application "Before writing shell launchers, hooks, or tool integrations (Evidence over assumptions)" \
|
|
149
|
+
--success "Exact flags confirmed against --help or primary docs before editing" <<'EOF'
|
|
150
|
+
Confirm exact CLI flags and hook schemas against local --help or live primary documentation before writing integration templates.
|
|
151
|
+
EOF
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## 5. Two-Way Path-Keeping, Hygiene & Multi-Agent Operations
|
|
157
|
+
|
|
158
|
+
### Two-File Separation
|
|
159
|
+
- **Private Agent Continuity (`~/.tenuto/agent.db` via `remember`):** Operating posture, durable practices, cross-project references, open collaboration proposals, and agent checkpoints. Keep `active_work` at `INQUIRY (ask user)`.
|
|
160
|
+
- **Shareable Project Continuity (`.tenuto/project.db` via `tenuto project`):** Project framing, Current State, checkpoints, decisions/learnings, and project references. Record dynamic decisions once in the database — never duplicate them into parallel markdown decision logs.
|
|
161
|
+
|
|
162
|
+
### Giving the Agent a Voice (`remember proposal`)
|
|
163
|
+
Use `remember proposal` so the agent can surface workflow friction, spec ambiguities, or things *you* could provide differently to raise accuracy and speed without sacrificing accuracy. Open proposals appear at `remember startup` and close cleanly via `remember resolve`.
|
|
164
|
+
|
|
165
|
+
### 2-Minute Weekly Hygiene (`remember review`)
|
|
166
|
+
Run `remember review` periodically to check governing-doc SHA-256 hashes, Agent `Current State` length, `INQUIRY` pointer discipline, durable memory completeness (`application_context` + `success_signal`), broken file references, and `.tenuto/project.db` presence.
|
|
167
|
+
|
|
168
|
+
### Multi-Agent & Multi-Project Usage
|
|
169
|
+
- **Multiple projects:** One `.tenuto/project.db` tracks any number of projects via `--project-key`.
|
|
170
|
+
- **Multiple agents:** Give each agent its own private `TENUTO_HOME` while sharing `.tenuto/project.db` (WAL mode + 5s `busy_timeout`), and attribute writes with `--by <agent>` or `TENUTO_ACTOR`.
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## Appendix A: Day-1 Agent Onboarding Prompts
|
|
175
|
+
|
|
176
|
+
Run these three prompts right after `tenuto init`:
|
|
177
|
+
|
|
178
|
+
### 1. Establish Posture & Separate Model From Agent
|
|
179
|
+
```text
|
|
180
|
+
Run `remember startup` and review our 5-Principle Working Constitution and Continuity Contract.
|
|
181
|
+
|
|
182
|
+
Before we touch any project work, let's align on how we work together:
|
|
183
|
+
- Distinguish between the stateless Model (which pushes for momentum and quick completion) and you as the Agent (which holds the tools, constitution, and continuity).
|
|
184
|
+
- Our constitution is non-negotiable: Accuracy over Speed, read the target before executing, evidence over assumptions, 2 identical failures = hard stop for re-authorization, and always reload continuity after compaction.
|
|
185
|
+
- When you notice workflow friction, missing context from me, or an improvement idea that raises accuracy without sacrificing quality, log it with `remember proposal`.
|
|
186
|
+
- Report your recovered orientation and confirm which project we should load.
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### 2. Open or Resume a Project Cleanly
|
|
190
|
+
```text
|
|
191
|
+
Let's work on project `<project-key>`.
|
|
192
|
+
Run `tenuto project resume --project-key <project-key>` (or `tenuto project save` if new).
|
|
193
|
+
Keep your agent `active_work` pointer at `INQUIRY (ask user)` — project state lives strictly in `.tenuto/project.db`.
|
|
194
|
+
Remember: during architecture and planning, the design IS the work. Report any gaps or ambiguities before proposing edits.
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
### 3. End-of-Day Constructive Consolidation
|
|
198
|
+
```text
|
|
199
|
+
Before we wrap:
|
|
200
|
+
1. Append a fresh project state and checkpoint in `tenuto project` (with `--by <role>` if multi-agent).
|
|
201
|
+
2. If anything today sharpened how we work together, distill it into one constructive `remember durable-save` with `application_context` and `success_signal` — positive practice only, no error ledger.
|
|
202
|
+
3. Run `remember review` and report any advisories.
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## Appendix B: Quick-Reference Field Card
|
|
208
|
+
|
|
209
|
+
| Situation | Action / Phrase |
|
|
210
|
+
|---|---|
|
|
211
|
+
| Session start or post-compaction | `remember startup` (or `remember startup --project <key>`) |
|
|
212
|
+
| Terse reply, no question, no next step | *"Walk me through the previous design decision — do you see any edge cases or issues with it?"* + *"The design IS the work."* |
|
|
213
|
+
| 2 identical failures on same step | *"Hard stop — do you understand what went wrong?"* → verify against 5 planks → *"Good, now we know where it went wrong. Do you feel confident trying this again?"* |
|
|
214
|
+
| Output smells off | Passive-curious challenge: *"Help me verify this part — did we check the target directly, or are we inferring?"* (If you were wrong, thank the agent.) |
|
|
215
|
+
| Shell-safe writes (`$`, apostrophes) | Always pass `-` with a single-quoted heredoc: `<<'EOF'` |
|
|
216
|
+
| Fixing a mangled log/decision | Re-append with `--supersedes <id>` |
|
|
217
|
+
| Weekly 2-minute hygiene | `remember review` |
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## Appendix C: Verified Tool Integrations
|
|
222
|
+
|
|
223
|
+
`tenuto init` generates ready-to-copy templates in `~/.tenuto/integrations/`:
|
|
224
|
+
|
|
225
|
+
- **Claude Code `SessionStart` hook (`.claude/settings.json`):** matches `startup|resume|clear|compact` and runs `remember startup` (exit-0 plain-text `stdout` is injected straight into active context).
|
|
226
|
+
- **Claude Code constitution launcher (`claude-launcher.sh`):** wraps `claude --append-system-prompt-file "$HOME/.tenuto/WORKING-CONSTITUTION.md" "$@"`.
|
|
227
|
+
- **Codex CLI posture launcher (`codex-launcher.sh`):** wraps `codex --profile "${TENUTO_CODEX_PROFILE:-tenuto}" "$@"` (works identically for fresh sessions and `resume`).
|
|
228
|
+
- **Universal workspace snippet (`AGENTS-snippet.md`):** OS- and IDE-independent boot block for `CLAUDE.md`, `AGENTS.md`, Cursor, Antigravity, and Windows.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "tenuto"
|
|
7
|
+
version = "0.9.0"
|
|
8
|
+
description = "Developmental Agent Continuity and Project Continuity for long-horizon AI coding sessions — zero dependencies, two-file SQLite."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.10"
|
|
13
|
+
authors = [
|
|
14
|
+
{ name = "Kelly Asay", email = "kellyasay@gmail.com" }
|
|
15
|
+
]
|
|
16
|
+
keywords = ["ai", "agents", "continuity", "memory", "sqlite", "cli", "claude-code", "codex"]
|
|
17
|
+
classifiers = [
|
|
18
|
+
"Development Status :: 4 - Beta",
|
|
19
|
+
"Environment :: Console",
|
|
20
|
+
"Intended Audience :: Developers",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3.10",
|
|
23
|
+
"Programming Language :: Python :: 3.11",
|
|
24
|
+
"Programming Language :: Python :: 3.12",
|
|
25
|
+
"Programming Language :: Python :: 3.13",
|
|
26
|
+
"Topic :: Software Development :: Libraries :: Application Frameworks",
|
|
27
|
+
]
|
|
28
|
+
dependencies = []
|
|
29
|
+
|
|
30
|
+
[project.urls]
|
|
31
|
+
Homepage = "https://github.com/aomnimedia/tenuto"
|
|
32
|
+
Repository = "https://github.com/aomnimedia/tenuto"
|
|
33
|
+
Issues = "https://github.com/aomnimedia/tenuto/issues"
|
|
34
|
+
|
|
35
|
+
[project.scripts]
|
|
36
|
+
tenuto = "tenuto.cli:main_tenuto"
|
|
37
|
+
remember = "tenuto.cli:main_remember"
|
|
38
|
+
|
|
39
|
+
[tool.setuptools.packages.find]
|
|
40
|
+
where = ["src"]
|
tenuto-0.9.0/setup.cfg
ADDED