docs: reframe org README around shared persistent workspaces - #7
Merged
Conversation
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
force-pushed
the
docs/org-readme-reframe
branch
from
April 29, 2026 22:02
38d8f25 to
155fd28
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
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).
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.
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
What's softened
Alignment
This is the third repo in the docs-reframe sequence, all from 2026-04-29:
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