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.
caelum0x 84c98681c9 feat: round-8 external harvest (15 features; web scout exhausted)
Final harvest round — gitgram-web scout returned no remaining valuable features.

- gitgram-mobile (5): swipe-to-reply, date dividers, swipe-to-action chat UX (bluesky)
- aitm-mcp (6): transport arg aliasing for hallucinated arg names (context7), + tool envelopes
- aitm-api (3): beads search endpoint + comments/notes over the DAG (beads)
- gitgram-backend (1): re-process @mentions on comment edit (munia)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-28 19:30:15 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00
2026-06-22 17:45:56 +03:00

gitgram-ai

Gitgram is the new GitHub — every repository is a TikTok/Instagram-style social profile. AITimeMachine (AITM) is the new Git — AI-native, deterministic version control with a unified memory layer and built-in agent orchestration.

This monorepo ships both products together: a repository-first social network on top of an AI-native version-control substrate.


Monorepo Map

gitgram-ai/
├── gitgram/                  # The social network (the "new GitHub")
│   ├── web/                  #   Next.js 14 + React 18 web app          (:3000)
│   ├── backend/              #   Express 5 + Prisma + GraphQL/tRPC/WS   (:4000)
│   └── mobile/               #   Expo 54 / React Native + expo-router
│
├── aitimemachine/            # The version-control substrate (the "new Git")
│   ├── api-server/           #   HTTP API over the engines (Drizzle ORM) (:3001)
│   ├── mcp/                  #   Model Context Protocol server (stdio/HTTP :3003)
│   ├── cli/  (src/cli*)      #   `aitm` command-line client
│   ├── website/              #   Marketing / docs site                  (:3002)
│   └── ─── 7 first-party engines (vendored, built in-tree) ───
│       ├── beads/            #   memory  — task/issue DAG (Go, Dolt-backed)
│       ├── context7/         #   memory  — up-to-date library docs (TS)
│       ├── git/              #   git     — real upstream Git (vendored C)
│       ├── gitnexus/         #   git     — code-intelligence graph (TS)
│       ├── a2a/              #   agentic — agent-to-agent protocol (TS)
│       └── pal-mcp-server/   #   agentic — Python agent execution (Python)
│                             #   (gitnexus-shared/ supports the gitnexus engine)
│
├── scripts/                  # Monorepo dev/ops scripts (dev.sh, smoke, verify)
├── docs/                     # Architecture, runbook, deploy, secrets, env matrix
└── docker-compose.yml        # Full local stack (Postgres + Redis + apps)

The seven engines are first-party: vendored, built, and managed as part of the product. There are no "assumed external service" seams — the old GITNEXUS_URL, CONTEXT7_URL, and PAL_MCP_URL environment seams have been removed.


AITM's 7 Merged Engines

AITM merges seven vendored repos as engines across three layers. Full wiring details live in aitimemachine/ENGINES.md.

Layer Engine Lang What it does How it's wired
Memory beads Go Task/issue DAG memory (Dolt-backed) Built to bin/bd; routes/beads.ts spawns it; tasks write through to memory
Memory context7 TS Up-to-date library/framework docs In-process @upstash/context7-sdk; CONTEXT7_API_KEY
Git git C The real upstream Git Built to bin/git; git-engine.ts shells out; checkpoints mirror to real commits
Git gitnexus TS Code-intelligence graph (Tree-sitter + LadybugDB) In-process via gitnexus/src/index.ts; gn_* MCP tools
Agentic a2a TS Agent-to-agent protocol @a2a-js/sdk (DefaultRequestHandler, InMemoryTaskStore, A2AClient)
Agentic pal Python Agent code execution / multi-model orchestration AITM-managed subprocess (palEngine.ts) speaking MCP over stdio

The seventh, gitnexus-shared, is a TS support library the gitnexus engine inlines at build time.

Both memory engines feed AITM's unified memory: services/memoryService.ts ingests beads tasks (source='task') and context7 docs (source='library') into saved_contexts with embeddings, so /v1/contexts/search/* returns them alongside conversation memory.


Quick Start

Prerequisites

Tool Version Needed for
Node.js 20+ all apps and engines
npm 10+ dependency install
Docker + Compose v2 latest Postgres, Redis, full stack
Go 1.21+ building the beads engine
make + cc any building the vendored git engine
Python 3.10+ building the pal engine venv

Engine builds soft-fail: a missing toolchain for one engine never blocks the others. git falls back to the system binary; missing engines simply report unavailable in the health endpoint.

1. Clone and bootstrap

git clone <repo-url> gitgram-ai && cd gitgram-ai

# One-shot dev setup: prereq checks, .env scaffolding, infra, deps, migrations
bash scripts/dev.sh

scripts/dev.sh copies every .env.*.example to its real counterpart (never overwriting), starts Postgres + Redis, runs npm ci for each package, and applies Prisma (Gitgram) and Drizzle (AITM) migrations.

Use bash scripts/dev.sh --infra to bring up only Postgres + Redis.

2. Build the AITM engines

bash aitimemachine/scripts/build-engines.sh

This builds the TS engine libraries, compiles beads → aitimemachine/bin/bd and git → aitimemachine/bin/git, provisions the pal Python venv under aitimemachine/engines/pal, and links workspace deps into api-server and mcp. Both bin/ and engines/ are git-ignored. Verify with GET /v1/health/providers.

3. Run the dev stack

docker compose up                        # Postgres + Redis + Gitgram + AITM API
docker compose --profile tools up        # + GitNexus + Context7 helpers

Or run individual services natively (hot reload):

npm run dev:gitgram-backend   # → http://localhost:4000   (GET /health)
npm run dev:gitgram-web       # → http://localhost:3000
npm run dev:aitm-api          # → http://localhost:3001   (GET /health)
npm run dev:aitm-mcp          # → stdio / http://localhost:3003

The AITM website is intentionally not started by the root compose file (to avoid a port clash with Gitgram web). Run it on :3002 separately:

cd aitimemachine/website && cp .env.example .env.local && PORT=3002 npm run dev

Environment variables

dev.sh scaffolds these from their .example siblings:

File Service
.env.gitgram Gitgram backend
.env.gitgram-web Gitgram web
.env.aitm-api AITM API server
.env.aitm-website AITM website
.env.postgres Postgres container

Key AITM engine vars (see ENGINES.md for the full matrix): CONTEXT7_API_KEY, AITM_GIT_BIN, AITM_GIT_MIRROR, BEADS_BINARY, PAL_VENV_DIR / PAL_PYTHON, AITM_MEMORY_USER_ID / AITM_MEMORY_PROJECT_ID. The full per-environment matrix lives in docs/environment-matrix.md.


Architecture at a Glance

        ┌──────────────┐     ┌──────────────┐
        │  Gitgram web │     │ Gitgram      │
        │  (Next.js)   │     │ mobile (Expo)│
        └──────┬───────┘     └──────┬───────┘
               │     GraphQL / tRPC / WebSocket
               └───────────┬────────┘
                           ▼
                ┌──────────────────────┐
                │  Gitgram backend     │   Express 5
                │  (controllers, jobs) │   Prisma ORM
                └──────────┬───────────┘
                           ▼
                 ┌───────────────────┐
                 │  Postgres + Redis │
                 └───────────────────┘

  ──────────────────  AITM substrate  ──────────────────

   ┌──────────┐    ┌──────────┐
   │ aitm CLI │    │   MCP    │  (Claude, IDEs, agents)
   └────┬─────┘    └────┬─────┘
        │   HTTP / MCP   │
        └───────┬────────┘
                ▼
      ┌────────────────────────┐
      │   AITM api-server      │  Drizzle ORM
      │   engineManager.ts     │  resolves bundled engine paths
      └───────────┬────────────┘
                  ▼
   ┌──────── 7 first-party engines ────────┐
   │ memory : beads (bin/bd) · context7     │
   │ git    : git (bin/git) · gitnexus      │
   │ agentic: a2a (@a2a-js) · pal (venv)    │
   └────────────────────────────────────────┘

  Gitgram ↔ AITM bridge: gitgramBridgeService.ts + routes/gitgram*.ts

For data flow, the unified memory layer, checkpoint mirroring, and how each MCP tool maps to an engine, see docs/ARCHITECTURE.md.


Testing

Each package owns its test suite:

npm test --prefix gitgram/web                  # Vitest + Testing Library
npm test --prefix gitgram/backend              # needs live Postgres + Redis
npm test --prefix aitimemachine/api-server     # Vitest + supertest
npm test --prefix aitimemachine                # Vitest (core + engines)

Engine and integration smokes:

bash aitimemachine/scripts/mcp-smoke-test.sh   # MCP tools end-to-end
bash aitimemachine/scripts/cli-smoke-test.sh   # aitm CLI
bash aitimemachine/scripts/a2a-smoke-test.sh   # agent-to-agent protocol
npm run smoke:local-launch                     # whole-stack local smoke gate

Deployment

Local and CI use Docker Compose (docker-compose.yml). Production runs on a single VPS following the manual launch contract in docs/runbook.md; docker-compose.prod.yml is a non-canonical full-docker reference.

Run release gates before any staging/production deploy:

npm run verify:aitm-packages
npm run verify:aitm-local
npm run verify:secrets:staging
npm run verify:secrets:production

Deploy pipeline and secrets contracts: docs/deploy-pipeline.md, docs/secrets-contract.md.


Contributing

  1. Read docs/ARCHITECTURE.md and aitimemachine/ENGINES.md to understand the layering.
  2. Run bash scripts/dev.sh then bash aitimemachine/scripts/build-engines.sh.
  3. Keep engines first-party — do not reintroduce external-URL seams.
  4. Add tests with your change; run the relevant suite and smoke scripts above.
  5. Run the verify/secrets gates before opening a deploy-bound PR.

Docs index

Description
Archived — renamed to Ritgram. Pre-rename prototype, kept as a reference.
Readme MIT 60 MiB
Languages
TypeScript 49%
Go 16.8%
C 14.5%
Shell 11.5%
Python 4.3%
Other 3.5%