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

7.8 KiB
Raw Permalink Blame History

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