Skip to content

fix(cortex): align KNOWLEDGE_CATEGORIES with current schema.md #128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TechNickAI merged 3 commits into from
Jul 15, 2026
Merged

fix(cortex): align KNOWLEDGE_CATEGORIES with current schema.md #128

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5887505
fix(cortex): align KNOWLEDGE_CATEGORIES with current schema.md
TechNickAI May 24, 2026
8c45736
fix(cortex): sync schema-template.md with new KNOWLEDGE_CATEGORIES
Jul 15, 2026
2e4e267
fix(cortex): sync schema + test fixtures with new KNOWLEDGE_CATEGORIES
Jul 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions skills/cortex/cortex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Comment thread
cursor[bot] marked this conversation as resolved.
]
Comment on lines 57 to 60

@chatgpt-codex-connector chatgpt-codex-connector Bot May 24, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Synchronize category list with deployed schema template

Updating KNOWLEDGE_CATEGORIES to people/ventures/topics/... without updating the schema that cortex setup deploys introduces a behavioral mismatch: _deploy_schema() still copies skills/cortex/schema-template.md, which instructs agents to use entities/concepts/summaries/how-to. On fresh setups this can send new pages into directories the CLI no longer scans in status/rebuild-index, causing missing counts and stale indexes again. Please update the deployed schema template (store layout + page type table) in the same change.

Useful? React with 👍 / 👎.

@TechNickAI TechNickAI Jul 15, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed — schema-template.md and the deployed schema now use the same category list. All references to entities/concepts/summaries/how-to have been replaced with the new names.


EXTRA_DIRECTORIES = ["learning", "learning/archive", "daily"]
EXTRA_DIRECTORIES = ["learning/archive", "daily"]

CONFIG_DIR = Path.home() / ".config" / "cortex"
CONFIG_FILE = CONFIG_DIR / "config"
Expand Down Expand Up @@ -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"

@cursor cursor Bot May 24, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Learning ops files counted

Low Severity

Adding learning to KNOWLEDGE_CATEGORIES makes cortex status count every .md in learning/ except index.md. Setup always creates learning/corrections.md and learning/patterns.md, so those operational logs inflate “Knowledge Pages” and the reported total even though they are not compiled knowledge pages.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 5887505. Configure here.

@TechNickAI TechNickAI Jul 15, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By design — learning/ is now a first-class category in KNOWLEDGE_CATEGORIES, so it's created by setup and counted by status. This is intentional (it was previously an 'extra' directory). The EXTRA_DIRECTORIES list was reduced accordingly.

"- [Recent Decisions](Knowledge Base/decisions/index.md)\n"
)
print("Created MEMORY.md routing table")
Expand Down
68 changes: 34 additions & 34 deletions skills/cortex/schema-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -75,8 +75,8 @@ 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
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

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
```
Expand All @@ -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
Expand All @@ -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`)

Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -463,8 +463,8 @@ Read the source. Identify:

For each identified element:

1. **Summary page** — Always create one in `summaries/` 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
Expand All @@ -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

Expand Down Expand Up @@ -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)
```

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
30 changes: 15 additions & 15 deletions tests/test_cortex.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
]


Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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"
Expand All @@ -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"
Expand All @@ -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"
)

Expand Down
Loading