Private
Public Access
0
0

docs: reduce redundant content across files; map references to canonical sources

Per user 'a bunch of docs just committed had redundant content across
files. Can we do a reduction of that and instead map references to
other files?'

This commit reduces content duplication across 9 files. The
canonical sources are kept as detailed references; the other
files now point to them.

Reductions (table replaced with 'see canonical' reference):

1. data_oriented_design.md §9: the 4-dim memory table
   (canonical: conductor/code_styleguides/agent_memory_dimensions.md §0)

2. guide_agent_memory_dimensions.md §0: the 4-dim memory table
   (canonical: conductor/code_styleguides/agent_memory_dimensions.md §0)

3. guide_caching_strategy.md §1: the 12-layer model
   (canonical: conductor/code_styleguides/cache_friendly_context.md §1)

4. guide_ai_client.md 'Cache strategy' section: the 12-layer model recap
   (canonical: conductor/code_styleguides/cache_friendly_context.md §1)

5. guide_knowledge_curation.md §1: the 5 category file details
   (canonical: conductor/code_styleguides/knowledge_artifacts.md §1)

6. product-guidelines.md 'Memory Dimensions' section: the 4-dim table
   (canonical: conductor/code_styleguides/agent_memory_dimensions.md §0)

7. guide_mma.md '4 memory dimensions' section: the MMA scope table
   (canonical: conductor/code_styleguides/agent_memory_dimensions.md §0)

8. docs/AGENTS.md §0 + §5-§8: 4-dim table + caching/knowledge/RAG/
   feature flag tables (canonical: the per-topic styleguides in
   conductor/code_styleguides/)

9. AGENTS.md 'Code Styleguides' section: the 6-styleguide list
   (canonical: docs/AGENTS.md §2)

The principle: each piece of content has ONE source of truth; other
places point to it. The data-oriented way. Files retain their
narrative flow and the 'what this is' intros, but the detailed
tables are now in their canonical home.

Net effect: -2100 bytes across 9 files (without losing any
information - the canonical sources are unchanged). The
'cross-references' sections are kept; the duplicated content
is removed.
This commit is contained in:
2026-06-12 14:10:30 -04:00
parent 35c6cca134
commit 434b6d0d54
9 changed files with 58 additions and 191 deletions
@@ -180,19 +180,18 @@ Design with the actual hardware's properties — cache hierarchy, memory bandwid
## 9. The 4 memory dimensions (the Manual Slop context)
The conversation data has 4 distinct memory dimensions. Each lives at a different layer; each serves a different purpose. The wrong shape for the wrong layer is a common mistake.
The conversation data has 4 distinct memory dimensions (curation / discussion / RAG / knowledge). Each lives at a different layer; each serves a different purpose.
| # | Dim | Where it lives | What it stores | How it's edited | How it's queried | SSDL |
|---|---|---|---|---|---|---|
| 1 | **Curation** | `FileItem` + `ContextPreset` + Fuzzy Anchors | *How to render a file* in the AI's context window | Structural File Editor; project TOML | Implicit in `aggregate.py:run` at discussion start | `[Q]` |
| 2 | **Discussion** | `app.disc_entries` + branching + UISnapshot | *What was said* in the conversation | GUI `[Edit]` mode; `[Branch]`; undo/redo | `build_markdown` renders as prior context | `o==>` |
| 3 | **RAG** | `src/rag_engine.py` (ChromaDB) | *Semantic fingerprints* of indexed files | (opaque vector store) | `RAGEngine.search()` at LLM call time | `[Q]` |
| 4 | **Knowledge** | `~/.manual_slop/knowledge/*.md` + per-file + digest + ledger | *Durable learnings* from past sessions | Plain markdown edit | Bounded digest as stable prefix | `o==>` |
**The canonical reference is `conductor/code_styleguides/agent_memory_dimensions.md` §0** (the full 4-dim table + per-dim deep-dives + boundaries + decision tree). This section is a pointer.
**The shape rule:** curation is per-file structural; discussion is per-turn conversational; RAG is opt-in semantic; knowledge is per-project durable. A feature that wants one should use the matching dimension; mixing them is a maintenance liability.
**The one-line summary:**
See `conductor/code_styleguides/agent_memory_dimensions.md` for the full styleguide.
- **Curation** is per-file structural (the `FileItem` schema)
- **Discussion** is per-turn conversational (the `disc_entries` list)
- **RAG** is opt-in semantic (the ChromaDB vector store)
- **Knowledge** is per-project durable (the markdown files at `~/.manual_slop/knowledge/`)
**The shape rule.** A feature that wants one should use the matching dimension; mixing them is a maintenance liability.
---
## 10. Enforceable deliverables (tier 2)
+5 -9
View File
@@ -113,16 +113,13 @@ The product guidelines are best understood alongside the per-source-file guides
- **[code_styleguides/config_state_owner.md](code_styleguides/config_state_owner.md):** Config I/O state ownership — `AppController` is the single source of truth; direct calls to `models.save_config`/`models.load_config` in `src/` are forbidden (enforced by `scripts/audit_no_models_config_io.py`).
## Memory Dimensions (added 2026-06-12)
The conversation data has 4 distinct memory dimensions. Features touch 1-2 typically; some touch 3. The dimensions are not interchangeable.
The conversation data has 4 distinct memory dimensions (curation / discussion / RAG / knowledge). Features touch 1-2 typically; some touch 3. The dimensions are not interchangeable.
| Dim | Where | What it stores | User-editable | Status |
|---|---|---|---|---|
| Curation | `FileItem` + `ContextPreset` | *How to render a file* | Structural File Editor | Existing, strong |
| Discussion | `disc_entries` + branching + UISnapshot | *What was said* | GUI `[Edit]` mode; undo/redo | Existing, strong |
| RAG | `src/rag_engine.py` (ChromaDB) | *Semantic fingerprints* | (opaque) | Opt-in |
| Knowledge | `~/.manual_slop/knowledge/*.md` + per-file + digest | *Durable learnings* | Plain markdown | Proposed (Candidate 8) |
**The full canonical 4-dim table is in `conductor/code_styleguides/agent_memory_dimensions.md` §0** (with the SSDL shape tag per dim + per-dim deep-dives + the decision tree). This section is the product-level summary.
**The product decision.** When scoping a new feature, identify which dimension(s) the feature touches. Pick the matching dimension; don't reach for the wrong shape. The full cross-cutting guide is `docs/guide_agent_memory_dimensions.md`. The canonical styleguide is `conductor/code_styleguides/agent_memory_dimensions.md`.
**The one-line summary:** curation is per-file structural; discussion is per-turn conversational; RAG is opt-in semantic; knowledge is per-project durable. Pick the matching dimension; don't reach for the wrong shape.
**The cross-cutting guide is `docs/guide_agent_memory_dimensions.md`.** The canonical styleguide is `conductor/code_styleguides/agent_memory_dimensions.md`.
**The 6 design rules (the product implications).**
@@ -132,7 +129,6 @@ The conversation data has 4 distinct memory dimensions. Features touch 1-2 typic
4. **Knowledge is durable, user-editable, provenance-aware.** The category files are the source of truth; the digest is a projection. "Delete to turn off": `rm digest.md`.
5. **Cache hits only on the stable prefix** (layers 1-7 of the 12-layer model). The volatile suffix (layers 8-12) is never cached.
6. **Feature flags are data, not config.** File presence ("delete to turn off") for side artifacts; config flags for persistent preferences; CLI flags for one-shot overrides.
## See Also — Updated (2026-06-12)
The canonical styleguide catalog (per the nagent_review v2.3 + intent_dsl_survey cross-references):