[shreyanshjain7174]

Proposed design, docs only. Nothing is built.

• P1 (uber: connect local agent harnesses with 1 command (P1) #71): 1-command connect for local harnesses: release binaries, a per-user home, zerodb connect, zerodb doctor, and README storage guidance.
• P2 (uber: automatic context capture for Claude Code (P2) #72): opt-in automatic capture through Claude Code hooks.
• P3 (uber: links and objects, images, video, files (P3) #73): links as refs, plus a local content-addressed object store for images, video and files, outside the tape.
• P4 (uber: compression, gated on dogfood numbers (P4) #74): compression, gated on dogfood numbers from stats: measure payload sizes and repeats before blobs or compression #36 and S6: dogfood zerodb as our agents' memory for 2 weeks #46.

Each phase lists the assumptions and open questions to confirm before it starts. Also marked:

• zerodb makes no outbound calls today. This proposes making that a decision. The decision log has no such rule yet.
• No S3 protocol server, and no fetching of link contents.

[Copilot]

🟡 Changes recommended

The proposed retry and disconnect contracts need clarification to prevent restoring forgotten content or overwriting unrelated configuration.

5 open issues

• Resolve conflicting object-sharing and storage-isolation policies · New
• Make hook deduplication durable beyond the bounded window · New
• Persist operation identity to prevent duplicate retry refs · New
• Clarify throughput gate as less than 5% loss · New
• Remove only managed config entries on disconnect · New

What changed in this PR

Adds a proposed, documentation-only roadmap for connecting local agent harnesses to zerodb and storing richer context. No functionality is implemented.

Changes:

• Defines installation, per-user configuration, harness registration, and opt-in Claude Code capture.
• Proposes link references and a local object store with durable writes and tenant-scoped access.
• Sets phased delivery gates, open questions, testing requirements, and evidence-based compression criteria.

File	Description
docs/​design/​0004-local-agents-and-objects.md	Introduces the four-phase proposal for local agents, capture, objects, and compression.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The proposed capture-progress lookup and object-directory sync sequence need corrections to support their duplicate-prevention and durability guarantees.

2 open issues

• Sync new shard parent directories before committing ObjectRef · New
• Persist transcript cursor independently per harness session · New

5 resolved since last review

• Remove only managed config entries on disconnect
• Clarify throughput gate as less than 5% loss
• Persist operation identity to prevent duplicate retry refs
• Make hook deduplication durable beyond the bounded window
• Resolve conflicting object-sharing and storage-isolation policies

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The proposed capture protocol still permits duplicate turns when overlapping hooks outlive dedup entries.

1 open issue

• Serialize cursor reconciliation and append to prevent duplicates · New

3 previously missed issues

In code that hasn't changed since last review

Clarify CLI tenant and data directory requirements

docs/​design/​0004-local-agents-and-objects.md:41

This overstates the current CLI requirements: --tenant takes a tenant name, not a path, and Adapter::new in crates/zerodb/src/mcp.rs accepts relative paths and can obtain data_dir from the config. The existing MCP launch tests also use relative paths successfully. Please distinguish the requirements for local auto-start from recommendations for harness registration so readers do not supply a path as the tenant or assume --data-dir is always mandatory.

Add XDG_DATA_HOME fallback for fresh Linux accounts

docs/​design/​0004-local-agents-and-objects.md:52

XDG_DATA_HOME can be unset or empty on a normal Linux account, so this does not define a usable per-user home for every fresh account covered by P1. Please specify the fallback to $HOME/.local/share/zerodb; otherwise the promised no-flags setup depends on users configuring an environment variable first.

Add destination parameter for non-inline object downloads

docs/​design/​0004-local-agents-and-objects.md:100

The proposed object_get arguments contain only the object identifier, but the non-inline branch requires a destination supplied by the caller. There is no argument through which callers can provide it, leaving downloads of recordings and other non-image objects undefined. Please include a destination parameter and specify what happens when a non-inline download omits it.

2 resolved since last review

• Sync new shard parent directories before committing ObjectRef
• Persist transcript cursor independently per harness session

_{Review effort: Balanced}

[shreyanshjain7174]

Also addressed the 3 previously missed issues in 16ce251:

• Current MCP flags: --tenant takes a name. The token comes from ZERODB_TOKEN, --token-file, or --config with --tenant. The server location comes from --url, --data-dir, or the config's data_dir. Relative paths resolve against the working directory. Absolute paths are a README recommendation for harness configs, not a requirement.
• Linux home: $XDG_DATA_HOME/zerodb if set and not empty, else $HOME/.local/share/zerodb.
• object_get {object, path?}: path is optional for small images, which come back inline, and required otherwise. zerodb never overwrites an existing file. Without path it returns an error with the size and type, and never writes to a default location.

[Copilot]

🟡 Changes recommended

The capture protocol still allows duplicate turns when an in-flight append outlives its hook and the retry occurs after deduplication eviction.

1 open issue

• Prevent duplicate appends after hook termination during in-flight commits · New

1 resolved since last review

• Serialize cursor reconciliation and append to prevent duplicates

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The proposed capture recovery and object-forget contracts need clarification to support their stated guarantees.

No open issues 🎉

2 previously missed issues

In code that hasn't changed since last review

Persist reconciliation progress across hook timeouts

docs/​design/​0004-local-agents-and-objects.md:81

If the intervening project history takes longer to scan than the hard hook timeout, each invocation restarts reconciliation from the same capture cursor and never reaches the append. Persist separate reconciliation progress as pages are scanned, without using other sessions' transcript positions as this session's capture cursor, or provide a bounded per-harness lookup.

Clarify forget semantics for duplicate object references

docs/​design/​0004-local-agents-and-objects.md:99

Two independent PUTs of identical bytes create refs for the same tenant and digest, so forgetting one ref can leave the object readable through the other, contrary to this promise. Define whether forget hides all matching refs through the I10 cutoff or hides the object only when no live refs remain. Include two independent PUTs followed by forget in the planned tests.

1 resolved since last review

• Prevent duplicate appends after hook termination during in-flight commits

_{Review effort: Balanced}

[shreyanshjain7174]

Addressed the 2 previously missed issues in cc3bf08:

• Reconciliation bound: each harness session now captures into its own zerodb session, <project session>/<harness session id>. Only that harness writes there, and each hook run appends at most 64 entries. So reconciling after the cursor reads at most 1 page, however busy the project is. A transcript further behind catches up over later hooks. SessionStart finds the newest capture session through a project/<name>/latest-capture fact. A test fills the project with 10,000 other turns between hooks.
• Object forget: a forget with an object: sha256:<hex> selector hides every ref the tenant holds to that digest, at or below the forget's LSN. A put after the forget makes a new, visible ref. Forgetting a turn hides the turn, not the object. A test covers 2 independent puts, then a forget, then a new put.

[Copilot]

🟡 Changes recommended

The capture design needs to account for byte-limited reconciliation and reconcile its completeness guarantees with the per-hook entry cap.

2 open issues

• Bound reconciliation batches by bytes, not just entry count · New
• Ensure capped recovery drains all pending entries durably · New

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The proposal needs bounded session identifiers and a retirement protocol that prevents capture writes after a concurrent forget.

1 open issue

• Coordinate session retirement with in-flight hook appends · New

1 previously missed issue

In code that hasn't changed since last review

Bound generated session IDs with UTF-8-safe truncation

docs/​design/​0004-local-agents-and-objects.md:68

Please bound generated session identifiers to the existing 255-byte limit enforced by crates/zerodb-core/src/turn.rs:106–107. A valid 255-byte project directory name already exceeds that limit once the hash is added, so default appends fail with invalid_input; capture's additional /<harness session id> suffix further reduces the available space. Specify UTF-8-safe truncation of the readable directory name, reserving space for the hash and capture suffix.

2 resolved since last review

• Persist object-put idempotency keys for replay recovery
• Prevent forgotten turns from replaying after cursor loss

_{Review effort: Balanced}

[shreyanshjain7174]

Also fixed the previously missed session-length issue in 10d020e. The default session is the directory name cut to 229 bytes on a UTF-8 boundary, plus -<8 hex>. Capture appends /<16 hex>, a hash of the harness session id, so every generated name fits in 255 bytes. The full harness id lives in the registration and the cursor fact. A test uses a 255-byte multibyte directory name.

[Copilot]

🟡 Changes recommended

The design needs project-isolated fact keys, filesystem authorization for object tools, and an explicit oversized-transcript policy.

2 open issues

• Use path-hashed project identity for pointers and fact prefixes · New
• Define filesystem authorization boundaries for model-callable tools · New

1 previously missed issue

In code that hasn't changed since last review

Handle oversized transcript entries without blocking capture

docs/​design/​0004-local-agents-and-objects.md:79

One transcript entry cannot always fit in one turn: turn::encode rejects content above 4 MiB (crates/zerodb-core/src/turn.rs:109), but this design places no corresponding limit on transcript entries. An oversized prompt or tool result therefore cannot be captured, and draining in order leaves every later entry stuck behind it on every hook and capture sync run. Specify deterministic size-bounded chunks with stable per-chunk retry identities and cursor-completion rules, or explicitly define an oversized-entry policy and narrow the completeness promise.

1 resolved since last review

• Coordinate session retirement with in-flight hook appends

_{Review effort: Balanced}

[shreyanshjain7174]

Also fixed the previously missed oversized-entry issue in 105c998. Entries over 4 MiB are split into chunks of at most 4 MiB, on UTF-8 boundaries at fixed offsets, so the same entry always splits the same way. Each chunk's idem_key is <harness session id>:<position>:<chunk>, and the cursor completes an entry only after its last chunk. Up to 16 chunks, 64 MiB, are stored. The rest is dropped and marked truncated, and completeness is stated for entries up to 64 MiB. Tests cover 10 MiB and 100 MiB entries with a kill between chunks.

[shreyanshjain7174]

Correction: my last 3 replies said "Fixed in 10d020e". That commit didn't contain those fixes, because my edit script stopped on one search string before writing anything. The fixes are in 105c998: path-hashed project ids, object tool roots, and chunked large entries. The replies' descriptions are accurate for 105c998.

[Copilot]

🟡 Changes recommended

The capture design needs encoded-size-safe chunk limits and chunk-aware recovery to support its stated completeness guarantees.

2 open issues

• Resume partial entries at the first missing chunk · New
• Derive chunk budgets from complete encoded transaction size · New

2 resolved since last review

• Define filesystem authorization boundaries for model-callable tools
• Use path-hashed project identity for pointers and fact prefixes

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The capture specification needs chunk sizes compatible with encoded write limits and explicit recovery of partially captured entries.

2 open issues

• Derive chunk budgets from complete encoded transaction size
• Resume partial entries at the first missing chunk

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The proposed capture sizing must account for JSON expansion against the HTTP body limit to avoid permanently blocking backlog capture.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Bound chunks by serialized request size to avoid permanent HTTP 413s

docs/​design/​0004-local-agents-and-objects.md:89

The 3 MiB content budget can exceed the 8 MiB HTTP body limit in crates/zerodb/src/http.rs:73,250–251: JSON encoding expands a chunk of U+001B characters to about 18 MiB. That chunk receives HTTP 413 on every retry, stalling the in-order capture drain. Bound deterministic chunks by both serialized request size and tape frame size, or explicitly plan an HTTP-limit increase; preserve 64 MiB entry coverage and add an escape-heavy boundary test (also update the chunking decision at line 173).

2 resolved since last review

• Derive chunk budgets from complete encoded transaction size
• Resume partial entries at the first missing chunk

_{Review effort: Balanced}

[shreyanshjain7174]

Fixed the previously missed HTTP-limit issue in b79df7d. A chunk is cut where the next character would take its raw size past 3 MiB or its JSON-escaped size past 7 MiB. That keeps it under both the 4 MiB frame limit and the 8 MiB HTTP body. Escaping is deterministic, so cuts are stable. Each chunk carries at least 7/6 MiB raw, so 64 chunks cover at least 74 MiB, and 64 MiB completeness holds. A test uses a 64 MiB entry made only of U+001B and asserts no 413. The decision-log row is updated.

[Copilot]

🟢 Approval recommended

The proposal clearly separates planned work from existing behavior, with only a minor test-fixture clarification remaining.

1 open issue

• Use an escape-heavy or larger fixture to test the 64-chunk cap · New

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The documentation clearly separates proposed features from existing behavior, records implementation gates, and has no unresolved blocking findings.

No open issues 🎉

1 resolved since last review

• Use an escape-heavy or larger fixture to test the 64-chunk cap

_{Review effort: Balanced}