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>
13 KiB
AI Time Machine MCP API Spec (v0.1)
Design rules
- Project sandbox: server only reads/writes inside
project.rootPath. - CAS blobs: file contents stored by
sha256(bytes); manifest references blobs. - Checkpoint = pointers:
{manifestId, chatHead, termHead, capsule}. - Restore is atomic: write to temp dir → verify → swap.
- Clients are dumb: Cursor/Claude just call tools; server does filesystem work.
Data primitives
BlobRef
{
"hash": "hex_sha256",
"sizeBytes": 1234,
"mimeType": "text/plain"
}
FileEntry (in a manifest)
{
"path": "src/api.ts",
"hash": "hex_sha256",
"size": 1024,
"mode": 420,
"mtimeMs": 1735005600000
}
Manifest JSON (stored as blob)
{
"version": 1,
"rootRel": ".",
"capturedAt": "2025-12-24T05:00:00.000Z",
"ignore": ["node_modules/**",".git/**","dist/**"],
"files": [ /* FileEntry[] */ ]
}
MCP Tools
0) tm_health
Purpose: basic health + version info.
InputSchema
{ "type": "object", "properties": {}, "additionalProperties": false }
Output
{ "ok": true, "version": "0.1.0", "dataDir": "/abs/.tmdata" }
1) tm_project_register
Create/update a project entry.
InputSchema
{
"type": "object",
"required": ["projectId","name","rootPath"],
"properties": {
"projectId": { "type": "string", "minLength": 1 },
"name": { "type": "string", "minLength": 1 },
"rootPath": { "type": "string", "minLength": 1 },
"ignore": { "type": "array", "items": { "type": "string" } }
},
"additionalProperties": false
}
Output
{ "projectId": "p1", "createdAt": "ISO", "updatedAt": "ISO" }
2) tm_event_append
Append an event (chat/fs/terminal/tool output). Use this for real-time capture.
Event types (string enum):
chat.messagefs.change_batchterm.commandterm.output_chunkterm.exittool.calltool.resultcheckpoint.marker
InputSchema
{
"type": "object",
"required": ["projectId","type","ts","payload"],
"properties": {
"projectId": { "type": "string", "minLength": 1 },
"type": { "type": "string", "minLength": 1 },
"ts": { "type": "string", "minLength": 10 },
"payload": { "type": "object" },
"blobs": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": ["mimeType","text"],
"properties": {
"mimeType": { "type": "string" },
"text": { "type": "string" }
},
"additionalProperties": false
},
{
"type": "object",
"required": ["mimeType","dataBase64"],
"properties": {
"mimeType": { "type": "string" },
"dataBase64": { "type": "string" }
},
"additionalProperties": false
}
]
}
}
},
"additionalProperties": false
}
Output
{ "eventId": "uuid", "blobRefs": [ /* BlobRef[] */ ] }
3) tm_checkpoint_create
Create a checkpoint by scanning workspace and materializing a manifest + pointers.
InputSchema
{
"type": "object",
"required": ["projectId","name","scope"],
"properties": {
"projectId": { "type": "string", "minLength": 1 },
"name": { "type": "string", "minLength": 1 },
"scope": {
"type": "string",
"enum": ["files","files+chat","files+chat+terminal","full"]
},
"mode": { "type": "string", "enum": ["shallow","full"], "default": "shallow" },
"capsule": {
"type": "object",
"properties": {
"imageRef": { "type": "string" },
"imageDigest": { "type": "string" },
"workdir": { "type": "string" },
"env": { "type": "object", "additionalProperties": { "type": "string" } }
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Semantics
shallow: only read file bytes if (mtime/size) changed since last manifestfull: hash every file (slower, but safest)
Output
{
"checkpointId": "cp_123",
"createdAt": "ISO",
"manifestBlob": { "hash": "hex", "sizeBytes": 999, "mimeType": "application/json" },
"fileCount": 470,
"chatHeadEventId": "evt_...",
"terminalHeadEventId": "evt_..."
}
4) tm_checkpoint_list
List checkpoints for timeline UI.
InputSchema
{
"type": "object",
"required": ["projectId"],
"properties": {
"projectId": { "type": "string", "minLength": 1 },
"limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 },
"cursor": { "type": "string" }
},
"additionalProperties": false
}
Output
{
"items": [
{
"checkpointId": "cp_123",
"name": "Before refactor",
"createdAt": "ISO",
"scope": "files+chat",
"fileCount": 47,
"capsuleImageDigest": "sha256:..."
}
],
"nextCursor": null
}
5) tm_checkpoint_restore
Restore workspace (and optionally return chat context) to checkpoint.
InputSchema
{
"type": "object",
"required": ["projectId","checkpointId","mode","restoreScope"],
"properties": {
"projectId": { "type": "string", "minLength": 1 },
"checkpointId": { "type": "string", "minLength": 1 },
"mode": { "type": "string", "enum": ["safe","hard"] },
"restoreScope": { "type": "string", "enum": ["files","files+chat"] },
"backupCurrent": { "type": "boolean", "default": true },
"dryRun": { "type": "boolean", "default": false }
},
"additionalProperties": false
}
Deterministic restore semantics (atomic)
-
If
backupCurrent=true, server first copies current root to:.tm_backups/<ts>_<checkpointId>/(or a tar blob)
-
Write restored tree into temp dir:
.tm_tmp_restore/<checkpointId>/
-
Verify:
- all manifest files exist
- blob sizes match
-
Swap:
- rename current root to
.tm_tmp_old/<ts>/ - rename temp dir to root
- on Windows: do “move out then move in” strategy; avoid non-atomic rename across volumes
- rename current root to
-
If
mode=hard, delete any extra files not in manifest (during build temp tree, they won’t exist anyway) -
If
dryRun=true, return plan only
Output
{
"restored": { "filesWritten": 47, "dirsCreated": 12 },
"backupPath": ".tm_backups/2025-12-24T05-10-00_cp_123",
"chatHeadEventId": "evt_...",
"warnings": []
}
6) tm_diff_checkpoints
Compute file/chat/terminal differences between two checkpoints.
InputSchema
{
"type": "object",
"required": ["projectId","aCheckpointId","bCheckpointId"],
"properties": {
"projectId": { "type": "string", "minLength": 1 },
"aCheckpointId": { "type": "string", "minLength": 1 },
"bCheckpointId": { "type": "string", "minLength": 1 },
"includePatches": { "type": "boolean", "default": false },
"maxPatchBytes": { "type": "integer", "default": 200000 }
},
"additionalProperties": false
}
Output
{
"fileDiffs": [
{
"path": "src/api.ts",
"status": "modified",
"aHash": "aaa...",
"bHash": "bbb...",
"patchBlob": null
}
],
"chatDiff": { "aHead": "evt_a", "bHead": "evt_b", "messagesDelta": 12 },
"terminalDiff": { "commandsDelta": 5 }
}
If
includePatches=true, server generates unified diff and stores it as a blob, returningpatchBlob.
7) tm_fs_get_file
Fetch file content at a checkpoint (debugging + “show me old code”).
InputSchema
{
"type": "object",
"required": ["projectId","filePath"],
"properties": {
"projectId": { "type": "string", "minLength": 1 },
"filePath": { "type": "string", "minLength": 1 },
"checkpointId": { "type": "string" }
},
"additionalProperties": false
}
Output
{
"filePath": "src/api.ts",
"hash": "hex",
"mimeType": "text/plain",
"text": "...."
}
Capsule tools (optional in v0.1 but recommended)
8) tm_capsule_upsert
Create or re-use capsule for project (pinned digest).
InputSchema
{
"type": "object",
"required": ["projectId","imageRef","workdir"],
"properties": {
"projectId": { "type": "string" },
"imageRef": { "type": "string" },
"workdir": { "type": "string" },
"env": { "type": "object", "additionalProperties": { "type": "string" } },
"ports": { "type": "array", "items": { "type": "integer" } }
},
"additionalProperties": false
}
Output
{ "capsuleId": "c_123", "imageDigest": "sha256:..." }
9) tm_capsule_exec
Exec command inside capsule; stream output via tm_event_append or return blob refs.
InputSchema
{
"type": "object",
"required": ["projectId","capsuleId","command"],
"properties": {
"projectId": { "type": "string" },
"capsuleId": { "type": "string" },
"command": { "type": "string" },
"cwd": { "type": "string" },
"timeoutMs": { "type": "integer", "default": 60000 }
},
"additionalProperties": false
}
Output
{
"exitCode": 0,
"stdoutBlob": { "hash": "hex", "sizeBytes": 123, "mimeType": "text/plain" },
"stderrBlob": { "hash": "hex", "sizeBytes": 0, "mimeType": "text/plain" }
}
Resources (read-only URIs)
These are nice for clients to browse.
tm://projectstm://projects/{projectId}/checkpointstm://projects/{projectId}/checkpoints/{checkpointId}/manifesttm://blobs/{hash}tm://projects/{projectId}/timeline?from=...&to=...
Error model
All tools return errors as MCP tool errors with a structured JSON payload.
Error shape
{
"error": {
"code": "TM_PATH_ESCAPE",
"message": "filePath resolves outside project root",
"details": { "filePath": "../secrets" }
}
}
Canonical error codes
TM_PROJECT_NOT_FOUNDTM_CHECKPOINT_NOT_FOUNDTM_MANIFEST_CORRUPTTM_BLOB_MISSINGTM_PATH_ESCAPETM_PERMISSION_DENIEDTM_IO_ERRORTM_CONFLICT_LOCKED(restore while capture running)TM_TOO_LARGE(blob/event exceeds limit)TM_CAPSULE_NOT_AVAILABLETM_CAPSULE_EXEC_FAILED
Deterministic restore details (implementation notes)
Path safety
For every filePath:
- resolve
realpath(join(root, filePath)) - assert it starts with
realpath(root)
Locking
-
Use a per-project lock file:
.tm_lock(advisory)
-
tm_checkpoint_restorefails withTM_CONFLICT_LOCKEDif capture running.
Atomic swap strategy
-
Build restore tree in
.tm_tmp_restore/<checkpointId>/ -
Verify counts/hashes
-
Swap directories:
- POSIX:
rename(tmp, root)after moving old root out - Windows: ensure moves happen on same volume; if not, do copy + replace
- POSIX:
-
Always write to temp first. Never partially overwrite the real tree.
Cursor/VSCode integration contract (what the extension sends)
On project open
tm_project_register({projectId, name, rootPath, ignore})
On file save (debounced batch)
Extension collects within 2–5 seconds:
-
list of changed paths
-
for each, either:
- send full text as blob in
tm_event_appendor - just send metadata and let server rescan on checkpoint
- send full text as blob in
Recommended MVP: send metadata only, server hashes on checkpoint (less bandwidth and simpler). Use:
{
"type": "fs.change_batch",
"payload": {
"changed": [{"path":"src/api.ts","reason":"save"}],
"editor": "cursor"
}
}
On chat message
{
"type": "chat.message",
"payload": {
"tool": "cursor",
"threadId": "t_abc",
"role": "user|assistant",
"content": "..."
}
}
On terminal command (managed terminal)
Before running:
tm_event_append(type=term.command, payload={sessionId, cwd, command})
Stream outputs:
tm_event_append(type=term.output_chunk, blobs=[{mimeType:'text/plain', text:'...'}])
On exit:
tm_event_append(type=term.exit, payload={exitCode})
Auto-checkpoint rule in extension OR server:
-
if command matches
/test|build|lint/and exitCode==0:- call
tm_checkpoint_create(name="Tests passed", scope="files+chat+terminal")
- call
When user says “go back”
Agent flow:
-
tm_checkpoint_list -
choose checkpoint
-
tm_checkpoint_restore(mode="hard", restoreScope="files+chat") -
client rehydrates restored chat context:
- create a new thread message: “Restored context: …”
- or show in a “Restored Context” panel
What you should implement first (minimal set)
Server MVP
tm_healthtm_project_registertm_event_appendtm_checkpoint_createtm_checkpoint_listtm_checkpoint_restoretm_diff_checkpoints(hash-level first; patches optional)
Extension MVP
- register project
- capture chat messages (Cursor UI hook)
- capture terminal commands (managed runner)
- create/restore checkpoints from command palette