Skip to content

docs: reframe org README around shared persistent workspaces - #7

Merged
chazmaniandinkle merged 1 commit into
mainfrom
docs/org-readme-reframe
Apr 29, 2026
Merged

docs: reframe org README around shared persistent workspaces#7
chazmaniandinkle merged 1 commit into
mainfrom
docs/org-readme-reframe

Conversation

@chazmaniandinkle

Copy link
Copy Markdown
Contributor

Summary

Replaces the old "AI agents need persistent memory" framing with a sharper thesis: every modern AI tool already has memory; what's missing is shared memory across tools, machines, and orgs. CogOS is the substrate underneath that solves that. Three substantive changes:

  1. New opener. Leads with the cross-tool / cross-device / cross-org gap and the "hierarchical like git remotes, but recursive" framing. The persona is a Claude Code or Cursor user feeling fragmentation friction, not someone who needs to be told that AI tools forget things (most of them don't anymore).

  2. New three-piece architecture diagram. AI tools → kernel → workspace overlay. Replaces the seven-module diagram, which referenced archived openclaw reconciler providers and tried to surface every implementation detail at once. New ".cog/ and .git/" section explicitly positions the cognitive overlay as a sibling to git, with content-addressed cross-references rather than duplication.

  3. New 'Workspaces compose' section. Names the recursive upstream pattern as the operational expression of selective sovereignty: workspaces have upstreams the way git repos do; those upstreams have their own upstreams; promotion across the hierarchy is explicit. This is the load-bearing differentiator and was missing entirely from the old README.

What's cut

  • TRM name and "Tiny Recursive Model" expansion (retired internal name)
  • NDCG@10 numbers, LOC counts, test counts (volume metrics)
  • Em-dash substitutes (`--`) in body prose, replaced with commas/periods/parens/colons
  • Old seven-module diagram with archived openclaw references
  • Em-dash in original body line ("any language — the wire protocol is the contract")

What's softened

  • Constellation row in the repos table reframed as L1 trust-node protocol (aligned with cogos-dev/constellation#7, merged earlier today)
  • Research row reframed away from EA/EFM/LoRO acronym soup, toward "notes and the training pipeline behind the kernel's design choices"
  • Kernel features rewritten as a lean seven-bullet summary that names externalized attention as the conceptual frame and reconcilers as a primary kernel function

Alignment

This is the third repo in the docs-reframe sequence, all from 2026-04-29:

  1. cogos-dev/constellation#7 — constellation README + PAPER (merged)
  2. cogos-dev/cogos#84 — cogos README (merged)
  3. This PR — org README

Net result: the three public-facing surfaces describe the substrate consistently. Visitors can land on any of them and not get a contradictory mental model.

Test plan

  • Read top-to-bottom, confirm flow: pain → solution → diagram → overlay → hierarchy → kernel features → repos → quickstart
  • Confirm no `—` or `--` in body prose
  • Confirm no TRM, NDCG numbers, LOC counts, test counts
  • Confirm constellation row matches the framing in cogos-dev/constellation
  • Confirm `.cog/` and `.git/` sibling framing matches the cogos README

Replaces the old 'AI agents need persistent memory' framing with a
sharper thesis: every modern AI tool already has memory; what's
missing is shared memory across tools, machines, and orgs. CogOS is
the substrate underneath that solves that.

Substantive changes:

- New opener leads with the cross-tool / cross-device / cross-org gap
  and the 'hierarchical like git remotes, but recursive' framing.
- New three-piece architecture diagram (AI tools to kernel to
  workspace overlay), replacing the dense seven-module diagram. The
  old diagram referenced openclaw reconciler providers (archived).
- New '.cog/ and .git/' section explicitly positions the cognitive
  overlay as a sibling to git, not a replacement, with content-
  addressed cross-references rather than duplication.
- New 'Workspaces compose' section names the recursive upstream
  pattern as the operational expression of selective sovereignty.
- Kernel features rewritten as a lean seven-bullet summary that names
  externalized attention as the conceptual frame and reconcilers as
  a primary kernel function.
- Repos table cleaned up. Constellation row reframed as L1 trust-node
  protocol (matching the recently-merged constellation rewrite).
  Research row reframed away from EA/EFM/LoRO acronym soup.
- Quickstart adds 'cogos init' as a step before 'serve'.
- Em-dash substitutes ('--') swept from body prose; commas, periods,
  parens, colons used instead.
- TRM name retired throughout. NDCG@10 / LOC / test count metrics
  removed.

Aligned with myrgic/cogos#84 (cogos README) and
myrgic/constellation#7 (constellation README) so the three repos
describe the substrate consistently.
@chazmaniandinkle
chazmaniandinkle force-pushed the docs/org-readme-reframe branch from 38d8f25 to 155fd28 Compare April 29, 2026 22:02
@chazmaniandinkle
chazmaniandinkle merged commit 53a1e01 into main Apr 29, 2026
@chazmaniandinkle
chazmaniandinkle deleted the docs/org-readme-reframe branch April 29, 2026 22:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant