OSS/podman
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: finalize PodMan architecture and write full integration specs

Browse Source 
Replaces v1 plan with locked architecture:
- Hermes orchestrator: POST /ingest → Gemini Vision → MongoDB → event detection → Gemini Live 2.5 voice via LiveKit Agents
- Four MongoDB collections: engineer_states, ownership_map, events, nudges
- Continual learning via ownership_map persisting across sessions

New files: docs/idea.md, docs/gemini.md, docs/livekit.md, docs/mongodb.md, docs/digitalocean.md, docs/demo-setup.md
Updated: README.md, docs/PLAN.md (12-hour build plan), database/README.md, infra/README.md, .env.example

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FFbfi4Cmb7BY75Wtne7bZn
This commit is contained in:
Ramis
2026-06-27 15:23:36 -07:00
parent e26961d526
commit 923ab1cf58
13 changed files with 1313 additions and 210 deletions
Download Patch File Download Diff File Expand all files Collapse all files
database/README.md
+23 -21
View File
@@ -1,32 +1,34 @@
# database
Continual-learning memory for PodMan: **MongoDB Atlas** for the team model and
outcomes, **Voyage** embeddings for vector recall. This is what makes PodMan
"more useful the more you use it" (the track requirement).
Persistent memory for PodMan: **MongoDB Atlas** stores live engineer state, the ownership map (continual learning), coordination events, and nudge history.
This is what makes PodMan "more useful the more you use it" — the ownership map persists across sessions, so PodMan already knows who owns what when the team comes back.
## Collections
| Collection | Holds | Notes |
| ---------------- | ---------------------------------------------- | ----------------------------- |
| `pods` | `Pod` docs (members, repo) | one per pod |
| `observations` | `EngineerContext` snapshots over time | sampled, append-only |
| `collisions` | detected `Collision`s | for replay + precision tuning |
| `interventions` | `Intervention`s + outcome (accepted/dismissed) | drives the self-tuning policy |
| `memory_vectors` | Voyage embeddings of file/feature notes | Atlas Vector Search index |
| Collection | Holds | Notes |
|---|---|---|
| `engineer_states` | Latest `EngineerContext` per engineer | Upserted on every `/ingest` call |
| `ownership_map` | File → primary owner + contributors | Persists across sessions — the continual learning artifact |
| `events` | Detected coordination events (DEPENDENCY_READY, BLOCKER_DETECTED, DUPLICATE_WORK) | Append-only |
| `nudges` | Every voice nudge sent to the room | Used for cooldown checks (3 min between nudges) |
Types live in [`shared/`](../shared/src). Each engineer/file/feature note is
embedded with Voyage and stored alongside its source doc for retrieval by the
PodMan brain.
Full schemas with indexes in [`docs/mongodb.md`](../docs/mongodb.md).
## The continual-learning loop
## Continual learning loop
1. **Observe** → write `observations`.
2. **Store** → embed notes into `memory_vectors`.
3. **Predict** → collision detector + brain decide whether to intervene.
4. **Outcome** → update the `interventions` doc with accepted/dismissed.
5. **Adapt** → tune thresholds + ownership attribution from outcomes.
1. **Observe** — engineer POSTs frame → Hermes calls Gemini Vision → `EngineerContext`
2. **Store** — upsert `engineer_states`, upsert `ownership_map`
3. **Detect** — Hermes runs event detection over all active states
4. **Nudge** — voice nudge sent into LiveKit room, written to `nudges`
5. **Improve** — next session: Hermes loads `ownership_map` on startup, skips cold-start inference
## Setup
Create an Atlas cluster + a Vector Search index on `memory_vectors.embedding`,
then set `MONGODB_URI` and `VOYAGE_API_KEY` in `.env`.
Create a free Atlas M0 cluster, then set `MONGODB_URI` in `.env`.
Collections are created automatically on first write — no migration needed.
```bash
MONGODB_URI=mongodb+srv://<user>:<pass>@cluster.mongodb.net/podman
```