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
Architecture
This document goes deeper than the front-door README: it covers the end-to-end data flow, the unified memory layer, the git engine and checkpoint mirroring, the agentic communication path (a2a registry + pal subprocess), and how each MCP tool maps to an engine.
Two products live in one repo:
- Gitgram — a repository-first social network (the "new GitHub"). Every repo is a social profile with feeds, posts, and follows.
- AITimeMachine (AITM) — an AI-native version-control substrate (the "new Git") with a unified memory layer, real git underneath, code intelligence, and agent orchestration.
Gitgram is a product on top of AITM. AITM is the substrate that makes AI agents making dozens of PRs per day deterministic and recoverable.
1. Layered Topology
Clients
┌─────────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────────────┐
│ Gitgram web │ │ Gitgram │ │ aitm CLI │ │ MCP clients │
│ (Next.js) │ │ mobile (Expo)│ │ │ │ (Claude, IDEs) │
└──────┬──────┘ └──────┬───────┘ └────┬─────┘ └────────┬─────────┘
│ GraphQL/tRPC/WS │ │ HTTP / MCP │
└────────┬────────┘ └────────┬────────┘
▼ ▼
┌────────────────────┐ ┌────────────────────────┐
│ Gitgram backend │◀──bridge──▶│ AITM api-server │
│ Express 5 / Prisma│ │ Express / Drizzle │
└─────────┬──────────┘ └───────────┬────────────┘
▼ ▼
┌───────────────────┐ ┌──────────────────────┐
│ Postgres + Redis │ │ engineManager.ts │
└───────────────────┘ └──────────┬───────────┘
▼
┌──────── 7 first-party engines ────────┐
│ memory : beads · context7 │
│ git : git (C) · gitnexus │
│ agentic: a2a · pal │
│ (+ gitnexus-shared support lib) │
└────────────────────────────────────────┘
- Gitgram backend (
gitgram/backend) is an Express 5 app exposing GraphQL (@apollo/server), tRPC (@trpc/server), and Socket.IO WebSockets over Prisma + Postgres, with Redis for caching/queues. Controllers, jobs, models, and services are split by domain undersrc/. - AITM api-server (
aitimemachine/api-server) is the HTTP surface over the engines, using Drizzle ORM (Neon / node-postgres dual driver).engineManager.tsresolves bundled engine paths (bin/bd,bin/git,engines/pal) with first-party defaults — no external URLs. - The two products talk through a bridge:
services/gitgramBridgeService.tsplusroutes/gitgram.tsandroutes/gitgramWebhooks.ts, so Gitgram repo events can drive AITM memory/checkpoints and AITM can surface intelligence back to Gitgram.
2. Data Flow
Gitgram request path
- Web (
Next.js) or mobile (Expo/react-native) issues a GraphQL/tRPC call or opens a Socket.IO connection. - Express middleware authenticates and authorizes the request.
- A domain controller/service reads or writes Postgres through Prisma; hot paths and pub/sub use Redis.
- WebSocket events (
socket.io) push feed updates to connected clients. - Repo-level events relevant to version control are forwarded to AITM via the bridge.
AITM request path
- A client (
aitmCLI, an MCP client, or the Gitgram bridge) hits the api-server or speaks MCP over stdio/HTTP. - The route handler validates input, then calls a service.
- The service resolves the relevant engine through
engineManager.tsand either calls it in-process (context7, gitnexus, a2a) or spawns/shells out to a bundled binary or subprocess (beads, git, pal). - Side effects (tasks, docs, checkpoints) write through to the unified memory layer.
GET /v1/health/providersreports each engine's availability.
3. The Unified Memory Layer
AITM's defining feature is a single searchable memory that fuses three sources into
the saved_contexts table with vector embeddings.
beads tasks ──► source='task' ─┐
context7 docs ─► source='library' ─┼─► memoryService.ts ─► saved_contexts
conversations ─► source='memory' ─┘ (embeddings via embeddings.ts)
│
▼
GET /v1/contexts/search/*
services/memoryService.tsingests beads tasks and context7 docs, tagging each row withsaved_contexts.source(added in migration0005_add_saved_context_source.sql).services/embeddings.tsproduces the vectors so semantic search spans all three sources at once.- A search for "how does retention work" can therefore return a beads task, a context7 doc snippet, and a prior conversation memory in one ranked result set.
- When a request carries no user/project, write-through targets
AITM_MEMORY_USER_ID/AITM_MEMORY_PROJECT_ID; if those are unset, write-through is skipped (reads still work).
This is what lets agents accumulate durable, queryable context across sessions instead of re-deriving state every run.
4. The Git Engine + Checkpoint Mirroring
AITM uses the real upstream Git (vendored C source in aitimemachine/git/), not a
reimplementation. The Rust gitcore crate present in the tree is a non-functional stub
and is not used.
aitm checkpoint / before_action
│
▼
git-engine.ts ──► bin/git (or system git fallback)
│
├─► AITM session/checkpoint store (Drizzle)
│
└─► AITM_GIT_MIRROR=on ─► real git commit ◄── deterministic restore
src/core/git-engine.tsshells out tobin/git(built bybuild-engines.sh), falling back to the systemgitif the bundled binary is absent.AITM_GIT_BINoverrides the path;aitm git …is a passthrough.- Checkpoint mirroring: every AITM checkpoint is mirrored to a real git commit
when
AITM_GIT_MIRRORis enabled (the default). This gives deterministic, inspectable restore points backed by ordinary git objects — restores are exact, not approximate. gitnexus(withgitnexus-shared) layers a code-intelligence graph over the repo using Tree-sitter parsing and LadybugDB. It runs in-process viagitnexus/src/index.ts→LocalBackend.callTool;services/gitNexusService.tscalls it directly. This powers impact analysis, call/route tracing, and structural queries.
5. Agentic Communication (a2a registry + pal subprocess)
The agentic layer is how AITM coordinates multiple agents and runs their code.
┌──────────── a2a (in-process) ────────────┐ ┌──── pal (subprocess) ────┐
│ @a2a-js/sdk │ │ pal-mcp-server (Python) │
│ DefaultRequestHandler │ │ bundled venv (engines/ │
│ InMemoryTaskStore ◄── registry │ │ pal), MCP over stdio │
│ A2AClient │ │ via palEngine.ts │
└───────────────────────────────────────────┘ └──────────────────────────┘
agent ↔ agent messaging/tasks code execution / multi-model
- a2a (agent-to-agent protocol) is consolidated onto
@a2a-js/sdk. The hand-rolleda2aServiceis replaced; the agent registry is backed by the SDK'sInMemoryTaskStore, withDefaultRequestHandlerserving requests andA2AClientfor outbound calls. This standardizes how agents discover each other and exchange tasks/messages. TheAITM_A2A_AGENTSexternal seam was removed. - pal (Python agent execution) runs as an AITM-managed subprocess.
api-server/src/engines/palEngine.tsspawns the bundled venv (engines/pal, override viaPAL_VENV_DIR/PAL_PYTHON) and speaks MCP over stdio. It handles sandboxed code execution, notebooks, package installs, and multi-model orchestration.pal_*MCP tools route through it.
Together: a2a decides who does what, pal runs the code, and the memory layer remembers the outcome.
6. MCP Tools → Engines
The MCP server (aitimemachine/mcp) registers tools in groups under
src/tools/register-*.ts. Each group maps to one engine or to AITM core.
| Tool group / prefix | Backing engine | Representative tools |
|---|---|---|
register-core-tools / register-session-tools |
AITM core (git engine + memory) | before_action, after_action, create_checkpoint, restore_session, list_sessions |
register-beads-tools |
beads (memory) | task/issue DAG create, list, link |
register-context7-tools |
context7 (memory) | context7 library-doc lookup |
register-gitnexus-tools / register-analysis-tools |
gitnexus (git) | gn_query, gn_impact, gn_trace, gn_route_map, gn_explain, gn_cypher, gn_pdg_query, gn_api_impact, gn_rename, gn_check |
register-a2a-tools |
a2a (agentic) | agent register, send-task, list-agents |
register-pal-tools |
pal (agentic) | pal_execute, pal_analyze_code, pal_create_session, pal_install_package, pal_execute_notebook, pal_convert_notebook |
register-file-tools / register-workspace-tools / register-worktree-tools |
AITM core (git engine) | file scan, workspace, worktree ops |
register-github-tools / register-integration-tools / register-storage-tools / register-claude-tools |
AITM core / integrations | GitHub, storage, and Claude-side glue |
Resolution flow for any tool call:
MCP client → mcp/src/tools/register-<group>.ts → AITM service
→ engineManager.ts resolves engine
→ in-process call (context7/gitnexus/a2a) OR spawn (beads/git/pal)
→ optional memory write-through (memoryService.ts)
Core safety tools (before_action / after_action / create_checkpoint) wrap any
agent action in a checkpoint, so the git engine's mirroring guarantees the action is
recoverable — the foundation for letting agents make many PRs per day safely.
7. Health, Path Resolution, and First-Party Guarantees
services/engineManager.tsis the single place that resolves engine locations, always preferring bundled, first-party defaults (bin/bd,bin/git,engines/pal).GET /v1/health/providersreports each engine independently: gitnexus →gitNexusService.isAvailable(); context7 →CONTEXT7_API_KEYpresence; pal →palEngine.health(); beads →bin/bd --version; git → bundled-or-system.- Removed external seams:
GITNEXUS_URL,CONTEXT7_URL,PAL_URL,PAL_MCP_URL,AITM_A2A_AGENTS. Engines are part of the product, not assumed services.
See aitimemachine/ENGINES.md for the per-engine build wiring and the full environment-variable table, and environment-matrix.md for per-environment values.
8. Build & Migration Order (why it matters)
The TS engine libraries (gitnexus-shared, context7 SDK, a2a, gitnexus) must be
built before api-server/mcp can resolve their imports —
build-engines.sh enforces this order, then compiles the native engines
(beads, git) and provisions the pal venv, then links workspace deps. Database
migrations run independently per product: Prisma for Gitgram, Drizzle for AITM, both
driven by scripts/dev.sh.