Backend Integration

The backend ingests anchor data from connected repositories. It has no direct git access - it reads data exclusively through platform APIs (GitHub, GitLab, Bitbucket) triggered by webhooks.

Remote API Surface

The CLI calls these endpoints. There is no cloud upload/ingest pipeline - team sync is Git-first via the orphan branch.

Endpoint	Method	Auth	Required	Purpose
`/anchors/search`	POST	Bearer token	Yes	Search anchors/sessions with memory + answer synthesis
`/anchors/delta`	POST	Bearer token	Yes	Compare two anchors (what changed between them)
`/anchors/health`	GET	None	No	Health check (recommended convention, not called by CLI)

Self-Hosting

Point your CLI at your own server:

oobo settings set api_url https://oobo.mycompany.com

Your backend implements endpoints under /anchors.

POST `/anchors/search`

Search across anchors, sessions, and semantic memory. Returns full-text and memory hits, with an optional synthesized answer.

Request

{
  "query": "why did we build the auth middleware?",
  "since": "7d",
  "project": { "kind": "global", "value": null },
  "tool": "cursor",
  "limit": 20
}

Field	Type	Required	Description
`query`	string	Yes	Natural-language search query
`since`	string?	No	Time filter (e.g. `24h`, `7d`, ISO-8601)
`project`	object?	No	Scope: `{"kind": "global"}`, `{"kind": "project_name", "value": "..."}`, or `{"kind": "project_id", "value": "..."}`
`tool`	string?	No	Filter by tool name
`limit`	number	No	Max results (default 20)

Response

{
  "answer": "The auth middleware was built to handle JWT refresh tokens because session-based auth had scaling issues.",
  "hits": [
    {
      "source": "memory",
      "snippet": "Team decided JWT with refresh tokens because session-based auth had scaling issues",
      "anchor_sha": "def456",
      "score": 0.87,
      "memory_id": "mem_abc123",
      "author": "teddy",
      "session_ids": ["sess-3", "sess-4"],
      "project": { "name": "oobo-agent" },
      "timestamp": 1773100000
    },
    {
      "source": "fts",
      "project": { "id": "p1", "name": "staging-only" },
      "anchor_sha": "abc123",
      "session_id": "sess-1",
      "tool": "cursor",
      "tokens": 12000,
      "timestamp": 1773282899,
      "intent": "fix auth middleware",
      "snippet": "auth middleware token refresh",
      "score": 0.91
    }
  ]
}

Field	Type	When present	Description
`answer`	string?	When memory hits exist and synthesis succeeds	Synthesized 1-3 sentence answer to the query
`hits[].source`	string	Always	`"fts"` (full-text search) or `"memory"` (semantic memory). Defaults to `"fts"` if absent
`hits[].memory_id`	string?	Memory hits only	Unique memory identifier
`hits[].session_ids`	string[]?	Memory hits only	Sessions that contributed to this memory
`hits[].author`	string?	Memory hits only	Who created the anchor this memory came from
`hits[].anchor_sha`	string?	Both	Commit SHA (may be short)
`hits[].session_id`	string?	FTS hits	Single session ID
`hits[].tool`	string?	FTS hits	Tool name
`hits[].tokens`	number?	FTS hits	Token count
`hits[].intent`	string?	FTS hits	Commit intent
`hits[].snippet`	string?	Both	Matching text excerpt
`hits[].score`	number?	Both	Relevance score (0-1)
`hits[].project`	object	Both	`{ "id": "...", "name": "..." }`
`hits[].timestamp`	number?	Both	Unix timestamp

POST `/anchors/delta`

Compare two anchors to see what changed: category shifts, complexity changes, new areas, new techniques, and a narrative summary.

Request

{
  "anchor_sha": "abc123",
  "previous_sha": null,
  "repo_id": null,
  "git_remote": null,
  "full": false
}

Field	Type	Required	Description
`anchor_sha`	string	Yes	Commit hash of the anchor to inspect
`previous_sha`	string?	No	Explicit previous anchor to compare against. If null, auto-finds the previous anchor
`repo_id`	string?	No	Filter by repo ID
`git_remote`	string?	No	Filter by git remote URL
`full`	bool	No	If true, includes detailed narrative, decisions, techniques, sessions

Response (compact, `full: false`)

{
  "current": {
    "sha": "abc123",
    "message": "feat: add JWT auth",
    "author": "teddy",
    "timestamp": "2026-05-05T10:00:00Z",
    "project": "oobo-agent",
    "headline": "Implemented JWT authentication with refresh token rotation",
    "category": "feature",
    "outcome": "success",
    "complexity": "moderate"
  },
  "previous": {
    "sha": "def789",
    "message": "refactor: extract auth middleware",
    "author": "teddy",
    "timestamp": "2026-05-04T16:00:00Z",
    "project": "oobo-agent",
    "headline": "Extracted auth logic into reusable middleware",
    "category": "refactor",
    "outcome": "success",
    "complexity": "low"
  },
  "changes": {
    "category_shift": { "from": "refactor", "to": "feature" },
    "complexity_shift": { "from": "low", "to": "moderate" },
    "new_areas": ["core/security", "redis"],
    "new_techniques": ["token rotation", "Redis TTL"],
    "files_continued": ["src/core/security/auth.py"],
    "files_new": ["src/core/security/refresh.py"],
    "narrative": "Built on the extracted middleware to add full JWT auth with refresh tokens..."
  }
}

When full: true, the response adds current_detail and previous_detail objects with: narrative, key_decisions, techniques, areas_affected, blockers, intent, reasoning, and session info.

Error Responses

Status	Body	Description
404	`{"error": "anchor_not_found", "message": "..."}`	The specified anchor SHA was not found
500	`{"error": "internal_error", "message": "..."}`	Server error

The Orphan Branch

All anchor data lives on a Git orphan branch. As of v2.0.0, new installs write to oobo/anchors/v2. The legacy oobo/anchors/v1 branch is read-only and preserved for pre-2.0 data. Both branches have zero relationship to the repo’s code history - they contain only structured JSON metadata about commits enriched with AI session data, attribution, and transcripts. The CLI pushes to the oobo/anchors/v2 branch on every git push (via a pre-push hook). No user action is required.

Configurable Anchor Remote

Anchors may not live in the same repository as the code. Users can configure a separate Git remote for anchor data via .oobo/config:

[anchors]
remote = "git@github.com:org/repo-anchors.git"

Or via the CLI: oobo settings project set remote <value>

When [anchors].remote is configured, the CLI pushes the oobo/anchors/v2 branch to that remote instead of origin. Your backend must handle this by:

Monitoring .oobo/config on the default branch of connected repos for changes to [anchors].remote
When [anchors].remote points to a separate repo, register webhooks on that repo and listen for pushes to both oobo/anchors/v2 and oobo/anchors/v1 (legacy) there
When unset or set to a named remote (e.g. origin), anchors arrive via pushes to the same repository

The value can be either a named remote (e.g. oobo) or a full URL (e.g. git@github.com:org/repo-anchors.git). Your backend should resolve named remotes via the repository’s Git config or treat direct URLs as the target.

Push Behavior and Data Safety

Scenario	User-Visible Behavior	Data Loss?
Push succeeds	Silent - no output	No
Non-fast-forward (contention)	Auto-retries up to 5 times with fetch+reconcile	No
Permission denied	Warning on stderr: `failed to push oobo anchors: ...`	No - local branch intact
Remote doesn’t exist	Warning on stderr	No - local branch intact
Network failure	Warning on stderr	No - local branch intact

The user’s git push is never blocked. Anchor push failures are warnings only. The local oobo/anchors/v2 branch always has the complete data - the next successful push will include all pending anchors.

Directory Layout (Sharding)

oobo/anchors/v2
├── README.md
├── c8/
│   └── e12fa9b3d4abcdef1234567890abcdef123456/
│       ├── metadata.json            ← Anchor (commit-level)
│       ├── timeline.json            ← Multi-agent interactions (optional)
│       ├── 1/
│       │   ├── metadata.json        ← SessionLink (per-session)
│       │   ├── transcript.json      ← Redacted transcript (if transparency=on)
│       │   └── subagents/
│       │       └── 1/
│       │           ├── metadata.json   ← Subagent type/ID
│       │           └── transcript.json
│       └── 2/
│           ├── metadata.json
│           └── transcript.json
└── ...

The commit hash (40-char hex SHA) is split: first 2 characters → top-level directory, remaining 38 → subdirectory name.

Webhook Trigger

Discovery: Where Do Anchors Live?

Before processing webhooks, the backend must determine where a project’s anchors are pushed:

On repo connection, read .oobo/config from the default branch (if it exists)
Check for [anchors].remote - if set, anchors are pushed to that repo/remote
If unset, anchors are in the same repo on branch oobo/anchors/v2
Subscribe to pushes on the default branch (to detect config changes), oobo/anchors/v2, and oobo/anchors/v1 (legacy)
If a push to the default branch modifies .oobo/config, re-read [anchors].remote and update webhook registration accordingly

GitHub

Listen for push events where ref is refs/heads/oobo/anchors/v2. During the migration period, also monitor refs/heads/oobo/anchors/v1 for legacy data:

{
  "ref": "refs/heads/oobo/anchors/v2",
  "before": "abc123...",
  "after": "def456...",
  "commits": [
    {
      "id": "def456...",
      "message": "oobo: add anchor for c8/e12fa9b3d4.../metadata.json",
      "added": ["c8/e12fa9b3d4.../metadata.json", "c8/e12fa9b3d4.../1/metadata.json"]
    }
  ]
}

GitLab

Listen for push events where ref is refs/heads/oobo/anchors/v2 (and refs/heads/oobo/anchors/v1 for legacy data).

Bitbucket

Listen for repo:push events. Filter push.changes[].new.name == "oobo/anchors/v2" (and "oobo/anchors/v1" for legacy data).

Reading Files via Platform APIs

GitHub REST
GitHub GraphQL
GitLab
Bitbucket

List all files (recursive tree):

GET /repos/{owner}/{repo}/git/trees/oobo/anchors/v2?recursive=1
Authorization: Bearer {token}

Read a single file:

GET /repos/{owner}/{repo}/contents/{path}?ref=oobo/anchors/v2
Authorization: Bearer {token}
Accept: application/vnd.github.raw+json

Compare two commits (incremental processing):

GET /repos/{owner}/{repo}/compare/{before}...{after}
Authorization: Bearer {token}

query {
  repository(owner: "org", name: "repo") {
    object(expression: "oobo/anchors/v2:c8/e12fa.../metadata.json") {
      ... on Blob { text }
    }
  }
}

Use GraphQL for bulk reads - you can fetch multiple objects in one query.

List tree:

GET /api/v4/projects/{id}/repository/tree?ref=oobo/anchors/v2&recursive=true

Read file:

GET /api/v4/projects/{id}/repository/files/{path}/raw?ref=oobo/anchors/v2

List directory:

GET /2.0/repositories/{workspace}/{repo}/src/oobo/anchors/v2/?max_depth=10

Read file:

GET /2.0/repositories/{workspace}/{repo}/src/oobo/anchors/v2/{path}

Ingestion Strategy

On Webhook Push

Extract before and after SHAs from the webhook payload
Get the diff between those two commits
For each newly added XX/YYYY.../metadata.json (3 segments) → new anchor
For each newly added XX/YYYY.../N/metadata.json (4 segments, N is numeric) → new session link
For each newly added XX/YYYY.../N/transcript.json → session transcript
For each newly added XX/YYYY.../timeline.json → multi-agent timeline

Pattern Matching

XX/YYYY.../metadata.json              → Anchor metadata
XX/YYYY.../N/metadata.json            → SessionLink (N is 1-indexed)
XX/YYYY.../N/transcript.json          → Session transcript
XX/YYYY.../N/subagents/M/transcript.json → Subagent transcript
XX/YYYY.../timeline.json              → Multi-agent timeline

Full Sync (Initial or Recovery)

Fetch the recursive tree of oobo/anchors/v2 (and oobo/anchors/v1 for legacy data)
Filter paths matching anchor metadata pattern
Bulk-fetch all metadata files
Process in parallel - anchors are independent

Rate Limits

GitHub REST: 5,000 requests/hour (authenticated)
GitHub GraphQL: 5,000 points/hour
Use blob SHAs for deduplication

Key Invariants

Rule	Detail
One anchor per commit	Directory path is unique per commit hash
Sessions are 1-indexed	Subdirectories are `1/`, `2/`, `3/`…
Append-only	Anchors are never deleted from the branch
Idempotent	Re-pushing the same anchor overwrites with identical content
Consistency	`ai_added + human_added == added` always holds
Consistency	`ai_deleted + human_deleted == deleted` always holds
Ordering	Sessions are ordered chronologically (1 = earliest)

Edge Cases

Scenario	Behavior
Branch doesn’t exist yet	No oobo data - skip until first push to `oobo/anchors/v2` (or `oobo/anchors/v1` for legacy repos)
`session_ids` is empty	Pure human commit (`author_type` = `"human"` or `"automated"`)
`ai_percentage` is null	No AI involvement - treat as 0%
`is_estimated` is true	Token counts were estimated via tiktoken (~90% accuracy)
`link_type` is `"inferred"`	Session linked via time-window heuristic (±5min of commit)
Multiple anchors in one push	Process all - user committed multiple times locally then pushed
Transparency mode mixed	Check `transparency_mode` per anchor - some have transcripts, some don’t
`[anchors].remote` configured	Anchors arrive via a different repo - backend must follow the remote
`[anchors].remote` changes	Re-read `.oobo/config` on default-branch pushes, update webhook targets
Push failures (permissions etc.)	Data stays on user’s local branch - next successful push catches up

​Remote API Surface

​Self-Hosting

​POST /anchors/search

​Request

​Response

​POST /anchors/delta

​Request

​Response (compact, full: false)

​Error Responses

​The Orphan Branch

​Configurable Anchor Remote

​Push Behavior and Data Safety

​Directory Layout (Sharding)

​Webhook Trigger

​Discovery: Where Do Anchors Live?

​GitHub

​GitLab

​Bitbucket

​Reading Files via Platform APIs

​Ingestion Strategy

​On Webhook Push

​Pattern Matching

​Full Sync (Initial or Recovery)

​Rate Limits

​Key Invariants

​Edge Cases

Remote API Surface

Self-Hosting

POST `/anchors/search`

Request

Response

POST `/anchors/delta`

Request

Response (compact, `full: false`)

Error Responses

The Orphan Branch

Configurable Anchor Remote

Push Behavior and Data Safety

Directory Layout (Sharding)

Webhook Trigger

Discovery: Where Do Anchors Live?

GitHub

GitLab

Bitbucket

Reading Files via Platform APIs

Ingestion Strategy

On Webhook Push

Pattern Matching

Full Sync (Initial or Recovery)

Rate Limits

Key Invariants

Edge Cases