Yahya Alhinai
195 lines
4.7 KiB
Markdown
195 lines
4.7 KiB
Markdown
# MongoDB Atlas Integration Spec
|
|
|
|
Status: demo-backed / active
|
|
|
|
MongoDB Atlas is PodMan's shared memory. It stores live work observations,
|
|
collision predictions (with vector embeddings for recall), interventions,
|
|
outcomes, latest engineer state, the materialized Team memory graph, and async
|
|
Hermes job runs.
|
|
|
|
See also:
|
|
|
|
- [`docs/cont_learning.md`](cont_learning.md) for outcome-backed team memory,
|
|
graph materialization, and `$graphLookup` traversal.
|
|
|
|
---
|
|
|
|
## Current Collections
|
|
|
|
### `engineer_states`
|
|
|
|
Latest context per engineer. The local git watcher writes git fields; the vision
|
|
pipeline may write screen-derived fields. Each writer updates only its own
|
|
fields so MongoDB upserts merge cleanly.
|
|
|
|
Key fields:
|
|
|
|
- `podId`
|
|
- `name`
|
|
- `currentFile`
|
|
- `inferredTask`
|
|
- `confidence`
|
|
- `changedFiles`
|
|
- `diffStat`
|
|
- `recentCommit`
|
|
- `branch`
|
|
- `visionUpdatedAt`
|
|
- `gitUpdatedAt`
|
|
- `updatedAt`
|
|
|
|
Primary use: deterministic dirty/unpushed truth for collision detection and
|
|
graph discovery.
|
|
|
|
### `observations`
|
|
|
|
Structured perception events from consented screen context and agent inference.
|
|
|
|
Key fields:
|
|
|
|
- `podId`
|
|
- `engineerId`
|
|
- `currentFile`
|
|
- `symbol`
|
|
- `activity`
|
|
- `confidence`
|
|
- `observedAt`
|
|
|
|
Primary use: observe/store proof and active editing edges in the Team memory
|
|
graph.
|
|
|
|
### `collisions`
|
|
|
|
Predicted coordination risks, with memory enrichment for recall.
|
|
|
|
Key fields:
|
|
|
|
- `id`
|
|
- `podId`
|
|
- `file`
|
|
- `symbol`
|
|
- `engineers`
|
|
- `severity`
|
|
- `overlapKind` — optional; `file`/undefined for same-file collisions,
|
|
`research` for code-edit ↔ research overlaps.
|
|
- `researchTopic`, `researchSource`, `researcher`, `editor` — optional fields
|
|
present only for research overlaps.
|
|
- `memorySignature`
|
|
- `githubState`
|
|
- `detectedAt`
|
|
- `memoryText` — short text embedded for recall
|
|
- `embedding` — vector (Voyage `voyage-4-lite` or Gemini `gemini-embedding-001`)
|
|
- `embeddingProvider` — `voyage` | `gemini`
|
|
|
|
Vector index `collision_embedding` (Atlas Vector Search) powers `$vectorSearch`
|
|
recall in `backend/src/memory/vectors.ts`. When Atlas vector search is
|
|
unavailable, recall falls back to app-side cosine, then exact signature/file
|
|
matching.
|
|
|
|
Primary use: collision cards, vector + signature recall, and graph risk paths.
|
|
|
|
### `interventions`
|
|
|
|
Actions PodMan sent or suggested.
|
|
|
|
Key fields:
|
|
|
|
- `id`
|
|
- `podId`
|
|
- `collisionId`
|
|
- `kind`
|
|
- `message`
|
|
- `suggestedAction`
|
|
- `status`
|
|
- `createdAt`
|
|
|
|
Primary use: closing the loop from prediction to a visible card, Hermes message,
|
|
or urgent voice cue.
|
|
|
|
### `outcomes`
|
|
|
|
Human or verifier supervision recorded through `POST /api/outcome`.
|
|
|
|
Key fields:
|
|
|
|
- `podId`
|
|
- `interventionId`
|
|
- `collisionId`
|
|
- `accepted`
|
|
- `wasRealCollision`
|
|
- `recordedAt`
|
|
|
|
Primary use: accepted and dismissed outcomes drive exact recall, suppression,
|
|
and learned graph paths.
|
|
|
|
### `team_model`
|
|
|
|
Durable per-pod summary memory.
|
|
|
|
Key fields:
|
|
|
|
- `podId`
|
|
- `ownership`
|
|
- `hotspots`
|
|
- `graph`
|
|
- `updatedAt`
|
|
|
|
Primary use: stable Team memory, including seeded `graph` snapshots used after
|
|
live materialization and before demo fallback.
|
|
|
|
### `graph_nodes` and `graph_edges`
|
|
|
|
Normalized mirror of the Team memory graph for MongoDB traversal.
|
|
|
|
Indexes:
|
|
|
|
- `graph_nodes`: `{ podId: 1, id: 1 }` unique
|
|
- `graph_edges`: `{ podId: 1, source: 1 }`
|
|
|
|
Primary use: `GET /api/pods/:podId/graph/reach/:id` with `$graphLookup`.
|
|
|
|
### `hermes_jobs` and `hermes_job_events`
|
|
|
|
Async Hermes task runs delegated from the live conversation agent (see
|
|
`docs/hermes.md`).
|
|
|
|
- `hermes_jobs` — one doc per job (`id` unique; `{ sessionId, status, updatedAt }`
|
|
index). Fields: `id`, `podId`, `sessionId`, `prompt`, `contextScope`,
|
|
`riskLevel`, `successCriteria`, `status`, `finalSummary`, timestamps.
|
|
- `hermes_job_events` — append-only step log (`{ jobId, createdAt }` index):
|
|
`accepted`, `heartbeat`, `step_started`, `step_output`, `needs_confirmation`,
|
|
`step_completed`, `completed`, `aborted`, `failed`. Output is redacted +
|
|
truncated before storage and mirrored to the room over LiveKit.
|
|
|
|
Primary use: durable, replayable record of what Hermes did, streamed live to the
|
|
conversation UI.
|
|
|
|
---
|
|
|
|
## Graph Truth Order
|
|
|
|
`GET /api/pods/:podId/graph` follows this order:
|
|
|
|
1. Live graph from real collections.
|
|
2. Seeded graph from `team_model.graph` and mirrored graph records.
|
|
3. Demo fallback graph for stage safety.
|
|
|
|
Seeded and fallback graphs are acceptable for demos only when labeled honestly.
|
|
|
|
---
|
|
|
|
## Demo Proof Path
|
|
|
|
Observe screen/git state -> detect collision -> send intervention -> accept or
|
|
dismiss outcome -> recall similar event -> show changed graph or changed
|
|
behavior.
|
|
|
|
---
|
|
|
|
## What MongoDB Does Not Store
|
|
|
|
- Raw screenshot frames.
|
|
- Screen recordings.
|
|
- Secrets or credentials.
|
|
- Full terminal logs.
|
|
- Full Gemini response objects beyond extracted fields needed for memory.
|