This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/aitimemachine/docs/correction.md
caelum0x 49b183818c Unify gitgram + aitimemachine into the monorepo (de-submodule) and merge vendored engines
Convert gitgram/ and aitimemachine/ from embedded git repos (which showed as
opaque submodule gitlinks on GitHub) into fully-tracked first-party content.

AITM now merges its 7 vendored repos as first-party engines:
- memory: beads (Go task DAG) + context7 (docs SDK), unified into saved_contexts
- git: vendored C git (bundled binary) + gitnexus (in-process code intelligence)
- agentic: a2a (@a2a-js/sdk) + pal (AITM-managed Python subprocess)

Includes the full session's product build: Gitgram web/mobile/backend features,
AITM website/CLI/MCP, the unified memory layer, engine build tooling
(scripts/build-engines.sh, Dockerfile, CI), docs (README, ENGINES.md, ARCHITECTURE.md),
and extensive test suites.

Build artifacts, node_modules, external/, and gemini-cli are gitignored.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-23 14:14:09 +03:00

292 lines
7.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Got it. That earlier “kiro-cli” output is mixing **aspirational architecture** with **assumptions** that may be false (and even contradictory). Here’s a **spec of errors to fix** (call it a “delusion-buster spec”) plus the **correct, implementable reality** for MVP so your docs + product don’t drift.
---
# Kiro-CLI Delusion Fix Spec (AITimeMachine)
## 0) Ground-truth principles (what must be true)
* MCP server **cannot** “restore” anything by itself unless it has **permission + code** to write to the filesystem or capsule FS.
* “Restore chat” is **not** “rewrite the tool’s internal chat UI”; it’s “return historical messages + pointers so the client can rehydrate context”.
* “Global daemon auto-discovers everything” is risky: discovery must be **opt-in** and **sandboxed**.
---
## 1) False/unsafe claims in the chat output and fixes
### A) “Captures complete development state across Claude Code, Cursor, Aider, etc.”
**Problem**
* Each tool stores chats differently; some don’t expose APIs.
* Claiming “complete state” implies you can always read their chat DB/logs.
**Fix spec**
* Rephrase to:
* “Captures workspace + terminal + AI interactions for supported clients.”
* Add compatibility matrix:
* Cursor: ✅ via extension/webview capture + MCP
* VSCode: ✅ extension capture
* Claude Desktop/Claude Code: ✅ **via MCP tool calls**; ⚠️ “import history” only if local files exist and format supported
* Aider: ✅ parse its chat logs if present, otherwise via wrapper
**MVP requirement**
* “Supported paths” are explicit and documented; anything else is “best-effort import”.
---
### B) “Global daemon auto-discovers projects and captures every 5 minutes”
**Problem**
* Auto-discovery can be invasive and wrong (privacy, performance).
* “Every 5 minutes” isn’t sufficient to capture *before error* moments; you need **event-based** capture too.
**Fix spec**
* Discovery is **opt-in**:
* user runs `aitm init` inside project OR selects folder in UI
* Capture triggers:
* **event-based** (file save, terminal command exit, tool result)
* plus periodic snapshot (e.g. 5 min) as fallback
**MVP requirement**
* Must implement a per-project allowlist, not “scan home directory”.
---
### C) “Folder file diffs captured”
**Problem**
* Diffs don’t need to be captured; they can be computed later from manifests + blobs.
* Capturing diffs for all files every interval is expensive.
**Fix spec**
* MVP: store **full file content blobs** (CAS) + **manifests**.
* Diff computed on demand:
* hash compare to find changed files
* optional patch generation only for text files (bounded by size)
**MVP requirement**
* `tm_diff_checkpoints` returns hash-level diff; `includePatches=true` optional.
---
### D) “Claude Code: read from ~/.claude/projects/{id}/conversations/”
**Problem**
* This path is an assumption. May not exist, may differ by OS/version.
* Even if it exists, format may be binary/SQLite/encrypted.
**Fix spec**
* Remove hard-coded path from docs.
* Replace with:
* **Primary**: Claude uses MCP calls in real-time (tool results are recorded)
* **Optional Importers**: tool-specific import with feature flag and OS path mapping
* `aitm import claude --path <dir>`
**MVP requirement**
* Do not claim file-based Claude history import unless verified + tested.
---
### E) “Cursor: MCP integration - real-time capture”
**Problem**
* Cursor supports MCP, but “message capture” depends on how Cursor exposes chat events.
* MCP itself doesn’t “capture messages”; it’s a tool interface.
**Fix spec**
* Cursor capture is done by:
* Cursor invoking MCP tools (e.g., `tm_event_append`) for checkpoints/restore
* PLUS an extension/webhook-like bridge if Cursor can emit chat events
* If chat events aren’t available:
* Only capture tool calls and checkpoint metadata
* For chat, you store “context packets” when AI requests restore
**MVP requirement**
* Document exactly what Cursor can capture in v0.1.
---
### F) “CLI with 40+ commands”
**Problem**
* Overpromises scope and adds maintenance burden early.
**Fix spec**
* MVP CLI commands (10 max):
* `aitm init`
* `aitm status`
* `aitm checkpoint create/list/restore/diff`
* `aitm projects list`
* `aitm blobs gc`
* `aitm mcp`
* `aitm capsule up/exec/down` (optional)
**MVP requirement**
* Remove “40+” from docs until real.
---
### G) “Web UI for visualization”
**Problem**
* Web UI is optional; you can ship without it and still be valuable.
**Fix spec**
* MVP: VSCode/Cursor panel is the UI.
* Web UI postponed to Phase 2.
---
### H) “S3 backup capability”
**Problem**
* Phase 1 shouldn’t claim it unless implemented (auth, encryption, resumable uploads, retention).
**Fix spec**
* Phase 1: export/import archive:
* `aitm export --project p1 --out backup.aitm.tar.zst`
* Phase 2: S3 sync.
---
### I) “Go back to before error version of chat”
**Problem**
* You usually cannot “rewind” the tool’s internal conversation thread.
* You *can* provide restored messages and force the AI to use them.
**Fix spec**
* Define **Context Rehydrate**:
* `tm_checkpoint_restore` returns `chatSnapshot` or `chatHeadEventId`
* Client creates a new thread message:
* “Restored context at <time>: [messages…]”
* or uses client-specific API if available
**MVP requirement**
* Add a “rehydrate mode” contract in the integration docs.
---
## 2) Missing details in the earlier explanation (must add)
### A) Atomic restore semantics
Without atomic restore you risk partial writes if crash occurs.
**Spec**
* restore writes into `.tm_tmp_restore/<id>`
* verify manifest integrity
* swap directories (POSIX rename; Windows safe move strategy)
* keep backup by default
### B) Concurrency + locking
Capturer and restorer must not run simultaneously.
**Spec**
* per-project lock: `.tm_lock`
* tools that mutate FS require lock
### C) Ignore rules
Not defining ignore rules kills performance & leaks secrets.
**Spec**
* default ignore:
* `.git/**`, `node_modules/**`, `.venv/**`, `dist/**`, `target/**`, `.next/**`
* `.env`, `**/*key*`, `**/*.pem`, `id_rsa`, `wallet*.json` (or at least warn)
* allow user override
### D) Terminal capture reality
You can’t capture every terminal in system reliably; only managed sessions.
**Spec**
* MVP: only capture terminals created/managed by the extension or `aitm run <cmd>`
* Future: OS-level capture is out of scope
---
## 3) Correct MVP story (the one you should document)
### Capture
* Files: manifest + CAS blobs (only changed files hashed each cycle)
* Chat: events from clients that can emit them; otherwise “context packets”
* Terminal: managed commands + outputs as events
* Checkpoints:
* manual
* auto on “tests passed/build succeeded”
### Store
* `events.db` indexes event stream
* `blobs/` CAS for file contents and outputs
* `manifest` blob per checkpoint
### Restore
* `tm_checkpoint_restore` reconstructs folder from manifest → atomic swap
* returns `chatHead`/`chatSnapshot` for rehydration
* optional capsule to ensure deterministic environment
---
## 4) Actionable “fix list” to apply to your README/docs
1. Replace “complete development state across all AI tools” with “supported integrations + best-effort imports”.
2. Replace “auto-discover projects” with “opt-in project registration”.
3. Replace “captures diffs” with “stores manifests + blobs; diffs computed on demand”.
4. Remove unverified Claude filesystem paths; add optional importer with flags.
5. Add explicit “restore chat = rehydrate context” wording.
6. Cut Phase-2 claims (S3, Web UI, 40+ commands) from Phase-1 README; keep them in roadmap.
7. Add compatibility matrix + integration contract.
8. Add atomic restore + locking + ignore rules section.
---