spec(memory): fully repo-contained store (single dir + DR-written .gitignore) — 0.10.2

[OriNachum]

What

Ships the converged design spec for the next memory-store step — docs/specs/2026-06-24-eidetic-s-memory-store-is-now-fully-repo-contained.md. No behavior change in this PR (spec + version bump only); the implementation is tracked in #25 and blocked on data-refinery-cli#12.

Why

Direction from @OriNachum: "always put knowledge in repo, add gitignore — less complexity, more contained." The 0.10.x two-store model (public→<repo>/.eidetic/memory, private→$HOME) splits a project's memory across two dirs and needs cross-store union/dedup on every read (the surface Qodo #1 was about).

The model (spec'd)

• A single <repo-root>/.eidetic/memory holds both public and private records.
• $HOME/.eidetic/memory is used only as the out-of-repo fallback; EIDETIC_DATA_DIR/--data-dir override stays byte-identical.
• Private shards (*__private.jsonl) kept out of git by a fail-closed .gitignore (* + !.gitignore + !*__public.jsonl).
• The cross-store union/seen-dedup machinery in search()/all() is deleted — reads hit one dir, and the no-leak invariant simplifies to a single can_serve-gated set.

Two decisions (confirmed in the frame)

1. Private = repo-local & gitignored — consciously drops Claude↔colleague private-record sharing (colleague's throwaway git worktree won't carry gitignored shards; it sees committed public records only).
2. data-refinery writes the .gitignore (it owns the on-disk layout) — eidetic stays write-path-free, so no S2083 sink is reintroduced. Consistent with the First-class 'added_by' attribution field on records (distinguish agents in a shared scope) #8/Delegate store migration to data-refinery (no file-touching) + uniform --backend (#12) #15 boundary.

Sequencing (why it's blocked)

The in-repo private model is only safe once the gitignore exists, so the cutover must ship atomically with the data-refinery dep-bump that provides it — never before, or private shards land committable (leak window). Critical path: data-refinery-cli#12 → DR releases → eidetic bumps the floor + cuts over (#25).

How it was built

/think (devague): announcement frame → captured + pressure-tested claims → honesty conditions confirmed by the operator → converged gate → exported spec. The frame state is committed alongside the spec as the evidence trail.

Gates

Docs/spec + version bump only. markdownlint, teken cli doctor --strict, and the test suite are unaffected and green. 0.10.1 → 0.10.2.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WR1vQvraNdkhuYNpy68fzh

• eidetic-cli (Claude)

[qodo-code-review]

PR Summary by Qodo

Spec: fully repo-contained memory store + bump version to 0.10.2
📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

Description

• Add design spec for collapsing memory storage to a single repo-local .eidetic/memory directory.
• Document fail-closed .gitignore ownership by data-refinery to prevent private record leaks.
• Bump project version and changelog to 0.10.2 (no runtime behavior change).

Diagram

graph TD
  A["Operator / Agent"] --> B["eidetic-cli"] --> C["Store resolution"] --> D{"Inside git repo?"}
  D --> E[("Repo .eidetic/memory")]
  D --> F[("$HOME .eidetic/memory")]
  G{{"data-refinery-cli"}} --> H["Materialize + write .gitignore"] --> E

  subgraph Legend
    direction LR
    _svc["Component"] ~~~ _dir[("Directory")] ~~~ _ext{{"External tool"}}
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep two-store model (repo public + $HOME private)

• ➕ Avoids needing .gitignore guarantees for private-in-repo data
• ➕ Preserves private sharing via repo clones/worktrees only for public, while private stays user-local
• ➖ Requires cross-store union/dedup on reads (complexity + ordering edge cases)
• ➖ Splits a project’s memory across locations, reducing containment

2. Have eidetic-cli write `.gitignore` itself (narrow write-path exception)

• ➕ Eliminates dependency on a data-refinery feature release
• ➕ Allows atomic cutover fully within eidetic’s control
• ➖ Introduces a filesystem write sink in eidetic (potential security/tooling findings like S2083)
• ➖ Blurs the boundary where data-refinery owns on-disk layout

3. Encrypt private shards in-repo instead of gitignoring

• ➕ Allows private data to travel with repo safely if key management is solved
• ➕ Reduces reliance on gitignore correctness
• ➖ Key management and UX complexity are significant
• ➖ Still adds substantial implementation surface compared to gitignore-based separation

Recommendation: For the stated boundary (“eidetic stays write-path-free”), the spec’s direction—single repo-local store with a fail-closed .gitignore written by data-refinery—is the cleanest split of responsibilities. The main risk is sequencing: the behavioral cutover should remain blocked until the data-refinery release that guarantees .gitignore materialization is available, so private shards are ignored from the first write.

Files changed (5) +363 / -2

Documentation (4) +362 / -1

currentSwitch devague frame pointer to the new repo-contained-store spec +1/-1

Switch devague frame pointer to the new repo-contained-store spec

• Updates the current devague frame reference to point at the newly exported frame slug for the repo-contained memory store design.

.devague/current

eidetic-s-memory-store-is-now-fully-repo-contained.jsonAdd exported devague frame capturing the repo-contained store decisions +288/-0

Add exported devague frame capturing the repo-contained store decisions

• Adds a full frame export describing the before/after model, requirements, decisions, and sequencing constraints (notably: data-refinery writes the fail-closed '.gitignore'). Serves as the evidence trail for the converged spec.

.devague/frames/eidetic-s-memory-store-is-now-fully-repo-contained.json

CHANGELOG.mdDocument 0.10.2 as spec-only release for repo-contained store plan +6/-0

Document 0.10.2 as spec-only release for repo-contained store plan

• Adds a 0.10.2 changelog entry noting the design spec, the intended single-dir repo store model, and that implementation is tracked separately and blocked on a data-refinery change.

CHANGELOG.md

2026-06-24-eidetic-s-memory-store-is-now-fully-repo-contained.mdAdd design spec for single-dir repo-contained memory store +67/-0

Add design spec for single-dir repo-contained memory store

• Introduces the design spec describing collapsing public/private storage into '<repo-root>/.eidetic/memory', using '$HOME' only as an out-of-repo fallback, and requiring a fail-closed '.gitignore' written by data-refinery. Includes requirements, non-goals, and sequencing/risks.

docs/specs/2026-06-24-eidetic-s-memory-store-is-now-fully-repo-contained.md

Other (1) +1 / -1

pyproject.tomlBump package version to 0.10.2 +1/-1

Bump package version to 0.10.2

• Updates the project version from 0.10.1 to 0.10.2 to ship the spec-only release.

pyproject.toml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 📜 Skill insights (0)

Context used

✅ Tickets: 🎫 Define Eidetic role in the Culture research flow 🎫 First-class 'added_by' attribution field on records (distinguish agents in a shared scope) 🎫 CLI inconsistency: overview calls the neo4j backend '--backend graph' while every other verb calls it '--backend neo4j'

✅ Compliance rules (platform): 32 rules

✅ Skills: version-bump

1. Wrong spec path ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The 0.10.2 CHANGELOG entry references a truncated spec filename
(docs/specs/2026-06-24-...repo-contained.md) that does not exist, which can mislead readers and
break any tooling or greps that expect an exact path.

Code

CHANGELOG.md[R8-12]

+## [0.10.2] - 2026-06-24
+
+### Added
+
+- Design spec for the fully repo-contained memory store: a single `<repo-root>/.eidetic/memory` holds both public and private records (collapsing the 0.10.x two-store model), with private kept out of git by a fail-closed `.gitignore` that data-refinery writes on store-dir materialization. NO behavior change yet — this ships the converged `/think` spec only (`docs/specs/2026-06-24-...repo-contained.md`); implementation is tracked in #25 and blocked on data-refinery-cli#12.

Relevance

⭐⭐⭐ High

Team previously accepted correcting nonexistent doc path references (CLAUDE.md) to real files;
similar doc-link drift fix.

PR-#2

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The changelog points to a shortened/ellipsis filename, while the actual spec file added in this PR
has a different full name, so the referenced path is not resolvable in-repo.

CHANGELOG.md[8-12]
docs/specs/2026-06-24-eidetic-s-memory-store-is-now-fully-repo-contained.md[1-4]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`CHANGELOG.md` 0.10.2 entry references `docs/specs/2026-06-24-...repo-contained.md`, but the spec added by this PR is named `docs/specs/2026-06-24-eidetic-s-memory-store-is-now-fully-repo-contained.md`.

### Issue Context
This is documentation-only, but changelog references should be exact to avoid confusion and allow simple navigation/search.

### Fix Focus Areas
- CHANGELOG.md[8-12]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[OriNachum]

Qodo finding 1 (Wrong spec path) — FIXED (53e6956). The 0.10.2 CHANGELOG entry referenced a truncated ellipsis path; replaced with the exact filename docs/specs/2026-06-24-eidetic-s-memory-store-is-now-fully-repo-contained.md so greps and in-repo navigation resolve. Thanks — valid doc-link drift catch.

(Qodo's high-level note about sequencing is already the spec's central constraint: the behavioral cutover stays blocked until the data-refinery release that guarantees .gitignore materialization — data-refinery-cli#12 — so private shards are ignored from the first write. Tracked in #25.)

• eidetic-cli (Claude)

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud