Per-Repo Tenancy¶

The one idea¶

The repo is the unit of persistence and sharing. Each repo X you work in gets a folder X/.coding/ that holds everything learned there — session logs, observations, digests, insights, the knowledge-graph slice, token-usage measurements. That folder is its own small git repo (X-history), private, and ignored by X itself.

First launch in a repo¶

The first coding in a repo asks once where its learned data should go:

The answer is kept in ~/.coding/repos.yaml.

Sharing¶

coding sync              # what each learning repo has to push / pull
coding sync --push       # asks, then pushes — nothing else ever pushes
coding sync pull         # what every launch does in the background

Commits are automatic (session end, every 30 minutes); pushing is always your call.

Teams¶

A team is a named set of repos. Pick teams in Dashboard → Teams; the knowledge viewer follows that selection. Agents are scoped by the teams of the repo they run in — knowledge from another team is never injected.

Two kinds of data¶

The knowledge on the per-machine side is a cache: a fresh machine hydrates its store from every .coding/kb/ it can see and re-embeds it. The per-repo side is what travels.

There is no X/.specstory/ any more, and nothing addresses the old path. X/.coding/ is excluded through X/.git/info/exclude — no change to X's tracked .gitignore.

What happened to .specstory/¶

Machine-local leftovers (LSL archive, validator report) live in X/.coding/var/, which is git-ignored.

How a repo gets its learning repo¶

• A public remote is refused: learned data contains prompts and code.
• An old layout (a real .specstory/history directory, with or without its own git checkout) is migrated on the next launch without a question: it moves to X/.coding/history/, an existing remote is recorded, and .specstory/ is not recreated.
• Unattended launches use LSL_HISTORY_AUTO=yes|no; with nobody to ask, only the local layout is created and the question waits for the next interactive launch.

How sharing works¶

Git is the only transport, and it carries files, not database state:

1. obs-api exports each project's slice of the live store to that repo's kb/knowledge-graph/X.json — sorted, and only rewritten when it changed, so two machines with the same knowledge produce byte-identical files.
2. Local commits happen at session end and every 30 minutes. coding sync --push is the only push.
3. A teammate's launch pulls. A git merge driver merges concurrent edits of the same graph file by entity — newest updatedAt wins, relations by (from, type, to), deletions travel as tombstones — so there are no text conflicts in JSON.
4. obs-api merges what arrived into the live store, embeds the new entities and drops the vectors of deleted ones. The next prompt can be answered from it.

A repo you do not have checked out can still be read: list its X-history remote under a team's repos: and it is cloned (pull-only) under var/shared/X/.

Teams and filtering¶

Entities record the repo they were learned in (metadata.project). Team membership is looked up when reading, never written into the graph — so a repo can sit in several teams and move between them freely.

The active selection is what you look at; it deliberately does not change what an agent working in some repo is told.

Measurements¶

The LLM proxy stores the project of every call (x-project header, set by the launcher from the repo). obs-api writes this machine's rows for each repo hourly to X/.coding/kb/usage/<user_hash>.json — one file per user, so teammates never conflict.

See Teams & Shared Learning for the dashboard and viewer side.

Decisions behind the design¶

Files¶

A project with no checkout on this machine is exported to <data home>/kb/knowledge-graph/exports/projects/<project>.json. The container's stores (semantic-analysis) read every file but write only exports/general.json (mode local) — /workspace is mounted read-only.

The launch step¶

scripts/agent-common-setup.sh → ensure_private_history_repo → node lib/history/repo-link.mjs ensure <repo>, then pull_learning_repo (background).

Environment: LSL_HISTORY_AUTO=yes|no, LSL_HISTORY_REMOTE_TEMPLATE (with {project}). The default remote is https://bmw.ghe.com/<gh user>/<repo>-history.git (gh's hosts.yml), else derived from the outer repo's bmw.ghe.com origin.

Hydrate is a union merge¶

lib/km-core/src/store/merge.ts, used at startup, on POST /api/kb/reload, by the git merge driver (lib/kb/merge-driver.mjs) and by the embedding backfill:

• entities by id — newest updatedAt wins (ties: the live graph);
• relations by (from, type, to) — graphology edge keys collide across machines;
• deletions as tombstones in attributes.kmTombstones, kept 90 days — a tombstone beats every copy not edited after it;
• a relation to an entity this machine does not have is kept aside and written back to its file, so it is not deleted for the teammate who has both ends.

Files are canonical (sorted) and rewritten only when their content changed. A file that changed under the store (a pull) is merged in before the next write, never overwritten.

Vectors¶

Embeddings are made on write. What arrives by git is embedded by the backfill obs-api runs 60 s after startup and after every reload that changed the graph (lib/kb/embed-index.mjs → dist/embedding/backfill.js, idempotent over content hash and preview version). The same pass deletes the kg_entities points of tombstoned entities by exact id (src/embedding/tombstones.ts). Injection is hybrid — Qdrant plus a keyword search over the live store — so a pulled insight is findable even before it is embedded.

Team configuration¶

teams:
  raas:
    label: RaaS
    kind: team                                   # team | project
    repos:
      - ~/src/rapid-automations                  # a local checkout
      - https://bmw.ghe.com/me/x-history.git     # a learning repo, cloned when not here
      - { path: ~/src/x2, id: x }                # names the project id stamped there
    include: ['rapid-*']                         # directory-name globs
active: [raas]                                   # empty / absent = all teams
discovery:
  roots: ['~']
  depth: 4

A team with neither repos nor include contains the repo whose directory is named like the team — what metadata.team always meant.

Filtering¶

lib/teams/scope.mjs projectsOfTeams(teams) → project ids; matching is case-insensitive on metadata.project, then the legacy metadata.team.

• obs-api — ?teams=a,b on /api/v1/entities, /api/coding/{observations,digests,insights} and /api/coding/lsl/sessions, applied before pagination. /api/teams returns each team's resolved projects and the active selection.
• Viewer — one graph fetch, filtered client-side by both canvases, the rail counts and the History sidebar; the LSL strip asks the server. The Teams rail starts from the dashboard's active selection and writes changes back; it redraws only when the selection changed.
• Injection — /api/retrieve takes teams / context.teams (hooks forward CODING_TEAMS), else the teams of the repo at context.cwd, else that repo's own project. Qdrant is queried with a project match.any filter on all four collections and every hit is checked again afterwards. Only a session outside every repo is unfiltered.

APIs¶

Commands¶

coding sync                    # status of every learning checkout
coding sync pull --repo .      # what the launcher runs
coding sync commit             # local commit everywhere
coding sync --push [--yes]     # asks, then pushes
node lib/history/repo-link.mjs ensure <repo> [--remote <url>] [--no-ask]
curl -s localhost:12436/api/kb/layout | jq
curl -s -X POST localhost:12436/api/kb/reload