spike: investigate intended multi-repo Dewey setup and cross-repo knowledge isolation

[yvonnedevlinrh]

Question

What is the intended Dewey setup for an organization with multiple sibling repos, and is the current behavior — where each repo's Dewey instance silently fails to index sibling repos — consistent with that intent?

Context

uf init scaffolds each repo with:

1. A sources.yaml containing disk sources for all sibling repos (e.g., disk-gaze: ../gaze)
2. An opencode.json that spawns dewey serve --vault . as an MCP server

This implies cross-repo indexing is an intended capability. However, in practice it does not work when multiple repos are open simultaneously — the most common multi-repo workflow (e.g., reviewing PRs across the org).

Observed Behavior

1. Disk source indexing silently returns 0 documents

When a sibling repo has a .uf/dewey/dewey.lock file, disk source indexing for that repo completes instantly with 0 documents and no error or warning:

INFO dewey/source: fetching source source=disk-gaze type=disk
INFO dewey/source: source fetched source=disk-gaze documents=0    # ~1ms, no files walked

Tested across 6 repos:

Disk Source	Lock file in target?	Pages indexed
disk-gaze	Yes (active dewey serve, PID 762775)	0
disk-dewey	Yes (stale empty lock from uf init)	0
disk-unbound-force	Yes (active dewey serve --http :3333)	0
disk-homebrew-tap	No lock file	4
disk-local (self)	Yes, but same process owns lock	266

Correlation is exact. Even a stale 0-byte lock file (no active process) triggers the skip.

2. Knowledge stored in graph.db is isolated per repo

Each dewey serve --vault . creates its own graph.db in .uf/dewey/. Learnings stored via store_learning are persisted in the local vault's database only.

This means:

• A learning stored in the website's Dewey ("disk source indexing is blocked by dewey.lock") is invisible to agents working in the gaze repo
• Compiled knowledge articles synthesized from learnings are local to the repo that compiled them
• There is no mechanism for cross-repo knowledge sharing beyond what disk source indexing would provide — which is blocked by the lock issue above

The combination of these two behaviors creates isolated knowledge silos: each repo accumulates learnings, decisions, and compiled articles that sibling repos cannot access.

3. Multiple Dewey instances compete for sibling repos

Each OpenCode session spawns its own dewey serve. In a typical multi-repo workflow:

PID 1534    dewey serve --vault /projects/unbound-force --http :3333
PID 762775  dewey serve --vault /projects/gaze
PID 846232  dewey serve --vault /projects/gaze          # duplicate
PID 902878  dewey serve --vault /projects/website

Each instance tries to index the same sibling repos via disk sources, and each blocks the others via lock files.

Questions to Answer

1. Is the per-repo Dewey model the intended architecture? Or should there be a shared instance (the --http :3333 instance on unbound-force suggests this may have been planned)?

2. Should disk source indexing respect lock files? Disk indexing only reads .md files — it never writes to the sibling's graph.db. The lock protects the database, but it's being applied to read-only file walks.

3. Is silent 0-document return intentional? If lock-skipping is by design, should it at least log a warning so the failure is visible?

4. Should stale lock files be cleaned up? Empty lock files and lock files referencing dead PIDs currently block indexing indefinitely.

5. How should cross-repo knowledge sharing work? If learnings and compiled articles are per-vault, is there an intended mechanism for making them discoverable across repos?

Possible Directions

Approach	Cross-repo docs	Cross-repo learnings	Complexity
A. Read-only disk indexing — ignore locks when only reading .md files	Solved	Solved (if learnings are .md)	Low
B. Shared Dewey instance — one dewey serve --http for the workspace, per-repo configs connect to it	Solved	Solved	High
C. Lock-aware skip with warning — keep current behavior but make it visible	Not solved	Not solved	Low
D. Stale lock cleanup only — clean up dead locks, accept active-lock conflicts	Partially solved	Partially solved	Low

Environment

• Dewey v3.2.0
• 6 repos under /projects/, all scaffolded with uf init
• Each repo's opencode.json starts dewey serve --vault . as MCP

[yvonnedevlinrh]

Related failure modes hit in practice this week (filing as separate issues ( #115 + #116 + unbound-force/replicator#95) since they're distinct from the multi-repo/lock architecture
question here):

• Corrupt graph.db → silent non-persistent in-memory fallback,store_learning refused with a misleading "configure --vault" error
  (WAL never checkpointed; database disk image is malformed (779)).
• find_by_tag ignores learning frontmatter tag: (only matches inline #block-tags).
• (Replicator) hivemind_store sends tags but Dewey requires tag, so the proxy path fails -32602.

The lock-skip behavior described here (#106) and these are independent —this session's breakage was corruption + WAL, not sibling locks — but they compound the same symptom: learnings silently not being persisted or retrievable.