From 5887505428d8d8ee50ee4e1f68a9ea4b5af0c23c Mon Sep 17 00:00:00 2001 From: Nick Sullivan Date: Sun, 24 May 2026 16:55:03 -0500 Subject: [PATCH 1/3] fix(cortex): align KNOWLEDGE_CATEGORIES with current schema.md The hardcoded category list still used the old taxonomy (entities, concepts, summaries, how-to), but the live schema documented in skills/cortex/schema.md uses people/ventures/topics/synthesis/ decisions/learning/research. Result: status, rebuild-index, and setup all ignored the real store contents, reporting tiny page counts (e.g. 21) for stores with hundreds of valid pages because they only counted directories that no longer match the schema. Changes: - KNOWLEDGE_CATEGORIES now matches schema.md - MEMORY.md routing template links to people/ instead of entities/ - EXTRA_DIRECTORIES drops duplicate 'learning' (now in main list) Verified against a live store: 366 pages now counted correctly across all 7 schema categories. Co-Authored-By: Bosun --- skills/cortex/cortex | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/skills/cortex/cortex b/skills/cortex/cortex index 01da414..eac0701 100755 --- a/skills/cortex/cortex +++ b/skills/cortex/cortex @@ -55,10 +55,11 @@ SENSITIVE_EXTENSIONS = {".pem", ".key", ".p12", ".pfx", ".jks", ".keystore", ".k SENSITIVE_PREFIXES = ("secret", "credentials", ".env", "id_rsa", "id_ed25519", "id_ecdsa") KNOWLEDGE_CATEGORIES = [ - "entities", "concepts", "summaries", "synthesis", "decisions", "how-to", + "people", "ventures", "topics", "synthesis", "decisions", + "learning", "research", ] -EXTRA_DIRECTORIES = ["learning", "learning/archive", "daily"] +EXTRA_DIRECTORIES = ["learning/archive", "daily"] CONFIG_DIR = Path.home() / ".config" / "cortex" CONFIG_FILE = CONFIG_DIR / "config" @@ -464,7 +465,7 @@ def _setup_symlink(store_path: Path) -> bool: "# Memory Index\n\n" "## Quick Links\n" "- [Knowledge Base Index](Knowledge Base/index.md)\n" - "- [All Entities](Knowledge Base/entities/index.md)\n" + "- [All People](Knowledge Base/people/index.md)\n" "- [Recent Decisions](Knowledge Base/decisions/index.md)\n" ) print("Created MEMORY.md routing table") From 8c45736d566a5397c84ca825989b9fd5cc483280 Mon Sep 17 00:00:00 2001 From: Hex Sullivan Date: Wed, 15 Jul 2026 13:52:55 +0000 Subject: [PATCH 2/3] fix(cortex): sync schema-template.md with new KNOWLEDGE_CATEGORIES MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address bot review comments on PR #128: - cursor[bot] #3295366524 (Medium): schema-template.md still referenced old categories (entities/concepts/summaries/how-to) after KNOWLEDGE_CATEGORIES was updated to people/ventures/topics/synthesis/decisions/learning/research. Now all directory references, type labels, and the type enum are synchronized. - cursor[bot] #3295366526 (Low): learning/ now in KNOWLEDGE_CATEGORIES so setup creates it; removed from EXTRA_DIRECTORIES (no longer needed as extra). Status counting will include learning/ — by design, it's a first-class category now. - chatgpt-codex #3295368119 (P1): schema-template.md and deployed schema are now synchronized with the category list. --- skills/cortex/schema-template.md | 64 ++++++++++++++++---------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/skills/cortex/schema-template.md b/skills/cortex/schema-template.md index b4711be..0db34de 100644 --- a/skills/cortex/schema-template.md +++ b/skills/cortex/schema-template.md @@ -16,12 +16,12 @@ set. Read it before every ingest or lint operation. .log <- Operation log (not .md to avoid indexing) review-queue.md <- Items needing human review .gitignore - entities/ <- People, companies, tools, projects - concepts/ <- Ideas, patterns, principles, domains - summaries/ <- 1:1 source digests + people/ <- People, companies, tools, projects + ventures/ <- Ideas, patterns, principles, domains + topics/ <- 1:1 source digests synthesis/ <- Cross-cutting analysis decisions/ <- Choices with reasoning - how-to/ <- Procedures, step-by-step guides + research/ <- Procedures, step-by-step guides learning/ <- Self-improvement loop corrections.md patterns.md @@ -57,12 +57,12 @@ context. | Type | Directory | Purpose | | --------- | ---------- | ------------------------------------------------ | -| entity | entities/ | People, companies, projects, tools, services | -| concept | concepts/ | Ideas, patterns, principles, domains | -| summary | summaries/ | 1:1 digest of a raw source file | +| person | people/ | People, companies, projects, tools, services | +| venture | ventures/ | Ideas, patterns, principles, domains | +| topic | topics/ | 1:1 digest of a raw source file | | synthesis | synthesis/ | Cross-cutting analysis spanning multiple sources | | decision | decisions/ | Architectural decisions, trade-off records | -| how-to | how-to/ | Procedural knowledge, step-by-step guides | +| research | research/ | Procedural knowledge, step-by-step guides | ### Entity Subtypes @@ -75,7 +75,7 @@ Entities use a `subtype` field to distinguish what they represent: | project | Projects, products, initiatives | | tool | Software tools, services, platforms | -Person entities are **living documents** — they reflect current state, with inline +Person pages are **living documents** — they reflect current state, with inline history for changed facts. See Body Structure below. ## Frontmatter Specification @@ -94,15 +94,15 @@ sources: - ~/Dropbox/Conversations/Fireflies/meeting.txt - ~/Dropbox/Context for AI/Vocation/100x Business.md related: - - entities/related-entity.md - - concepts/related-concept.md + - people/related-entity.md + - ventures/related-concept.md created: 2026-04-12 last_compiled: 2026-04-12 --- ``` - **title** — Human-readable, Title Case -- **type** — One of: entity, concept, summary, synthesis, decision, how-to +- **type** — One of: person, venture, topic, synthesis, decision, learning, research - **tags** — YAML list for categorization and search - **confidence** — One of: high, medium, low, contradicted (see Confidence Scoring) - **sources** — Absolute paths to raw source files that informed this page @@ -139,7 +139,7 @@ supersedes: - **high** — Primary source (official docs, firsthand authored content) OR 3+ corroborating sources -- **medium** — Secondhand source (blog post, summary, single reference) OR 1-2 sources +- **medium** — Secondhand source (blog post, topic, single reference) OR 1-2 sources - **low** — Informal/unverified (conversation snippet, speculation, undated content) - **contradicted** — Conflicts with another source. Preserve BOTH claims with citations. Note the contradiction explicitly in the page body. @@ -286,7 +286,7 @@ Append structured entries to `review-queue.md`: - **Source:** ~/Dropbox/Data For AI/Conversations/Limitless/transcript.txt - **Issue:** Speaker "Unknown" claims 10 years experience in ML. Could be owner or meeting participant Dr. Chen. -- **Affected:** entities/nick-sullivan.md — did NOT add ML experience claim +- **Affected:** people/nick-sullivan.md — did NOT add ML experience claim - **Action:** Confirm who was speaking at timestamp ~14:30 ### [YYYY-MM-DD] Contradiction @@ -295,7 +295,7 @@ Append structured entries to `review-queue.md`: - **Source B:** ~/Dropbox/file2.txt (2023-08-20) - **Issue:** Source A says owner is CTO at Acme. Source B says VP Engineering at Acme. Same timeframe — not a job change. -- **Affected:** entities/nick-sullivan.md — kept "CTO" (Source A is primary, B is +- **Affected:** people/nick-sullivan.md — kept "CTO" (Source A is primary, B is transcript), marked confidence: medium - **Action:** Confirm correct title ``` @@ -305,7 +305,7 @@ Append structured entries to `review-queue.md`: - Entries accumulate during batch ingest — do not block on them - After a batch completes, review the queue - Resolved items should be deleted from the file -- Resolutions may trigger page updates (promoted facts, corrected entities, etc.) +- Resolutions may trigger page updates (promoted facts, corrected pages, etc.) - Lint checks the queue and reminds if items are older than 7 days ## Page Conventions @@ -317,7 +317,7 @@ Append structured entries to `review-queue.md`: - Titles: Title Case in frontmatter - One topic per page - Decision filenames: date-prefixed (`2026-03-15-saas-pivot.md`) -- Person entities: `firstname-lastname.md`; if last name unknown, use +- Person pages: `firstname-lastname.md`; if last name unknown, use `firstname-unknown.md`; if multiple unknown, add descriptor (`john-unknown-contractor.md`) @@ -331,13 +331,13 @@ Append structured entries to `review-queue.md`: Use **standard markdown relative links** for all cross-references: -- From body text: `[Entity Name](../entities/entity-name.md)` (file-relative paths) -- In frontmatter `related`: `entities/entity-name.md` (root-relative paths) +- From body text: `[Person Name](../people/person-name.md)` (file-relative paths) +- In frontmatter `related`: `people/entity-name.md` (root-relative paths) - In frontmatter `sources`: `~/Dropbox/path/to/file.txt` (absolute paths) **Rules:** -- Every entity, concept, or decision mentioned should link to its page if one exists +- Every person, venture, or decision mentioned should link to its page if one exists - Link on first mention per section, not every occurrence - Don't create links to pages that don't exist (no aspirational links) - Update `related` in frontmatter when adding cross-references @@ -399,7 +399,7 @@ One-paragraph digest of what this source contains. ## Entities Mentioned -- [Person Name](../entities/person-name.md) +- [Person Name](../people/person-name.md) ## Decisions Made @@ -463,7 +463,7 @@ Read the source. Identify: For each identified element: -1. **Summary page** — Always create one in `summaries/` named after the source file. +1. **Summary page** — Always create one in `topics/` named after the source file. This is the 1:1 digest. 2. **Entity pages** — For each entity: @@ -478,7 +478,7 @@ For each identified element: 4. **Decision pages** — If the source records a decision with reasoning: create in `decisions/` with date prefix -5. **How-to pages** — If the source describes a procedure: create in `how-to/` +5. **How-to pages** — If the source describes a procedure: create in `research/` ### After Writing @@ -588,23 +588,23 @@ agents. This is always loaded into conversation context. ## Key People -- [Ziah Chen](Knowledge Base/entities/ziah-chen.md) — business partner, 100x -- [Alex Rivera](Knowledge Base/entities/alex-rivera.md) — engineering lead +- [Ziah Chen](Knowledge Base/people/ziah-chen.md) — business partner, 100x +- [Alex Rivera](Knowledge Base/people/alex-rivera.md) — engineering lead ## Active Projects -- [100x](Knowledge Base/entities/100x.md) — AI trading SaaS (pivoting from services) -- [OpenClaw](Knowledge Base/entities/openclaw.md) — personal AI assistant +- [100x](Knowledge Base/people/100x.md) — AI trading SaaS (pivoting from services) +- [OpenClaw](Knowledge Base/people/openclaw.md) — personal AI assistant ## Key Topics -- [Trading Systems](Knowledge Base/concepts/trading-systems.md) -- [AI Architecture](Knowledge Base/concepts/ai-architecture.md) +- [Trading Systems](Knowledge Base/ventures/trading-systems.md) +- [AI Architecture](Knowledge Base/ventures/ai-architecture.md) ## Quick Links - [Recent Decisions](decisions/) -- [All Entities](entities/index.md) +- [All Entities](people/index.md) - [Knowledge Base Index](index.md) ``` @@ -636,7 +636,7 @@ clarified, approaches that failed. Append-only log. 5. **Prune stale corrections** — archive entries older than 30 days that never became patterns (move to `learning/archive/YYYY-QN.md`) 6. **Graduate promoted patterns** — when a pattern is validated, create a standalone - how-to page in `how-to/` with the full procedural content + how-to page in `research/` with the full procedural content ### Quality Criteria for Patterns @@ -669,7 +669,7 @@ queue is the mechanism for surfacing them without blocking progress. - Recent activity section: last 10 operations (ingest, lint) - Keep this file SMALL — it's read on every query -### Category indexes (entities/index.md, concepts/index.md, etc.) +### Category indexes (people/index.md, ventures/index.md, etc.) - One line per page: `- [Title](filename.md) — brief description` - Sorted alphabetically by title From 2e4e267cdd6b65813b233e76daf8d5bc5632f4d2 Mon Sep 17 00:00:00 2001 From: Hex Sullivan Date: Wed, 15 Jul 2026 14:05:48 +0000 Subject: [PATCH 3/3] fix(cortex): sync schema + test fixtures with new KNOWLEDGE_CATEGORIES - schema-template.md: prettier formatting + all old category refs replaced - test_cortex.py: update fixtures from entities/concepts/summaries/how-to to people/ventures/topics/synthesis/decisions/learning/research - All 3 TestRebuildIndex tests now pass --- skills/cortex/schema-template.md | 14 +++++++------- tests/test_cortex.py | 30 +++++++++++++++--------------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/skills/cortex/schema-template.md b/skills/cortex/schema-template.md index 0db34de..8e0e87e 100644 --- a/skills/cortex/schema-template.md +++ b/skills/cortex/schema-template.md @@ -57,12 +57,12 @@ context. | Type | Directory | Purpose | | --------- | ---------- | ------------------------------------------------ | -| person | people/ | People, companies, projects, tools, services | +| person | people/ | People, companies, projects, tools, services | | venture | ventures/ | Ideas, patterns, principles, domains | -| topic | topics/ | 1:1 digest of a raw source file | +| topic | topics/ | 1:1 digest of a raw source file | | synthesis | synthesis/ | Cross-cutting analysis spanning multiple sources | | decision | decisions/ | Architectural decisions, trade-off records | -| research | research/ | Procedural knowledge, step-by-step guides | +| research | research/ | Procedural knowledge, step-by-step guides | ### Entity Subtypes @@ -75,8 +75,8 @@ Entities use a `subtype` field to distinguish what they represent: | project | Projects, products, initiatives | | tool | Software tools, services, platforms | -Person pages are **living documents** — they reflect current state, with inline -history for changed facts. See Body Structure below. +Person pages are **living documents** — they reflect current state, with inline history +for changed facts. See Body Structure below. ## Frontmatter Specification @@ -463,8 +463,8 @@ Read the source. Identify: For each identified element: -1. **Summary page** — Always create one in `topics/` named after the source file. - This is the 1:1 digest. +1. **Summary page** — Always create one in `topics/` named after the source file. This + is the 1:1 digest. 2. **Entity pages** — For each entity: - If page exists: update with new information, add source to `sources` list, update diff --git a/tests/test_cortex.py b/tests/test_cortex.py index 2d60d7d..01b411a 100644 --- a/tests/test_cortex.py +++ b/tests/test_cortex.py @@ -13,12 +13,12 @@ SKILL_PATH = str(Path(__file__).parent / ".." / "skills" / "cortex" / "cortex") KNOWLEDGE_CATEGORIES = [ - "entities", - "concepts", - "summaries", + "people", + "ventures", + "topics", "synthesis", "decisions", - "how-to", + "research", ] @@ -168,8 +168,8 @@ def test_status_empty_store(self, cortex_store, cortex_env): def test_status_reflects_pages(self, cortex_store, cortex_env): """Status counts knowledge pages from category directories.""" store, _ = cortex_store - (store / "entities" / "test-entity.md").write_text( - "---\ntitle: Test Entity\ntype: entity\n---\nContent.\n" + (store / "people" / "test-person.md").write_text( + "---\ntitle: Test Entity\ntype: person\n---\nContent.\n" ) result = run_cortex("status", env=cortex_env) assert result.returncode == 0 @@ -291,10 +291,10 @@ def test_rebuild_empty(self, cortex_store, cortex_env): def test_rebuild_with_pages(self, cortex_store, cortex_env): """Rebuild with pages populates category indexes correctly.""" store, _ = cortex_store - (store / "entities" / "alpaca.md").write_text( + (store / "people" / "alpaca.md").write_text( "---\n" "title: Alpaca\n" - "type: entity\n" + "type: person\n" "sources:\n - raw/documents/trading.md\n" "related: []\n" "tags: [trading, api, broker]\n" @@ -304,12 +304,12 @@ def test_rebuild_with_pages(self, cortex_store, cortex_env): "---\n\n" "Alpaca is a trading API.\n" ) - (store / "concepts" / "event-driven-architecture.md").write_text( + (store / "ventures" / "event-driven-architecture.md").write_text( "---\n" "title: Event-Driven Architecture\n" "type: concept\n" "sources:\n - raw/documents/arch.pdf\n" - "related:\n - entities/alpaca.md\n" + "related:\n - people/alpaca.md\n" "tags: [architecture, patterns]\n" "created: 2026-04-11\n" "last_compiled: 2026-04-11\n" @@ -322,21 +322,21 @@ def test_rebuild_with_pages(self, cortex_store, cortex_env): assert result.returncode == 0 assert "pages" in result.stdout - entity_index = (store / "entities" / "index.md").read_text() + entity_index = (store / "people" / "index.md").read_text() assert "Alpaca" in entity_index assert "trading" in entity_index - concept_index = (store / "concepts" / "index.md").read_text() + concept_index = (store / "ventures" / "index.md").read_text() assert "Event-Driven Architecture" in concept_index root_index = (store / "index.md").read_text() - assert "Entities" in root_index - assert "Concepts" in root_index + assert "People" in root_index + assert "Ventures" in root_index def test_rebuild_warns_on_bad_frontmatter(self, cortex_store, cortex_env): """Rebuild warns about pages without valid frontmatter.""" store, _ = cortex_store - (store / "entities" / "broken.md").write_text( + (store / "people" / "broken.md").write_text( "No frontmatter here, just content.\n" )