chore: rename entity_type to note_type

[phernandez]

Summary

• Renames Entity.entity_type → note_type to eliminate confusion with SearchItemType (entity/observation/relation)
• Adds Alembic migration that renames the column + index on the entity table and updates search_index JSON metadata (both SQLite and Postgres)
• Updates ORM model, Pydantic schemas, services, repositories, API routers, MCP tools/clients, CLI commands, schema inference engine, and ~52 test files
• Renames SearchQuery.types → note_types and type alias EntityType → NoteType

Unchanged: SearchItemType enum, entity_types params filtering by entity/observation/relation, frontmatter YAML type: key, entity_metadata column.

Test plan

• just lint — pass
• just format — pass
• just typecheck — 0 errors
• just test-unit-sqlite — 1999 passed, 26 skipped
• just test-int-sqlite — 278 passed, 4 skipped
• CI: full SQLite + Postgres test suite

🤖 Generated with Claude Code

[github-actions]

Claude finished @phernandez's task in 2m 49s —— View job

---

PR Review: rename entity_type to note_type

This is a well-executed, comprehensive rename refactor. The change eliminates a genuine naming confusion between Entity.entity_type (note classification) and SearchItemType (entity/observation/relation), and the migration, ORM, schemas, services, repositories, MCP tools, and tests are all consistently updated.

---

Team Checklist

Code Quality & Standards

• Follows Basic Memory's coding conventions in CLAUDE.md
• Python 3.12+ type annotations and async patterns used throughout
• SQLAlchemy 2.0 best practices maintained
• FastAPI and Typer conventions followed
• 100-character line length limit maintained
• No commented-out code blocks

Testing & Documentation

• Unit tests updated (52+ test files) — 1999 unit + 278 integration tests passing
• Integration tests for MCP tools updated
• 100% test coverage maintained

Basic Memory Architecture

• Database changes include correct Alembic migration (SQLite + Postgres)
• MCP tools follow atomic, composable design
• Knowledge graph operations maintain consistency
• Markdown file type: frontmatter key intentionally unchanged ✓
• SearchItemType enum intentionally unchanged ✓
• entity_types param for SearchItemType filtering intentionally unchanged ✓

Security & Performance

• No hardcoded secrets or credentials
• No sensitive data in logs or commits
• Proper error handling maintained

Compatibility

• No emoji/unicode characters introduced in console/log output

---

Detailed Findings

Migration — Well Done

src/basic_memory/alembic/versions/j3d4e5f6g7h8_rename_entity_type_to_note_type.py

• Idempotent upgrade guard (column_exists) is correct and important.
• Using ALTER TABLE entity RENAME COLUMN directly for SQLite (3.25.0+) instead of batch_alter_table is the right call — avoids the known failure on tables with generated columns.
• JSON metadata migration (search_index.metadata) correctly handles both SQLite (json_set/json_remove) and Postgres (jsonb operator chain).
• Downgrade function is complete and correct. Note: the downgrade lacks an idempotency guard (unlike the upgrade), but this is standard Alembic practice since Alembic tracks state externally.

Minor: Stale EntityType reference in a test comment

tests/api/v2/test_schema_router.py:6:

# Note: EntityType uses BeforeValidator(to_snake_case) so "Person" becomes "person"

The Python type alias was renamed from EntityType → NoteType. This comment should be updated to reference NoteType.

Fix this →

Minor: Unrelated changes bundled in PR

pyproject.toml adds cst-lsp>=0.1.3, libcst>=1.8.6 to dev deps and reportUnusedImport = "none" to pyright config. These come from the separate prior commit ("add cstlsp to dev deps") and are unrelated to the rename. Not blocking, but ideally these would be on a separate branch/PR to keep history clean.

Note: EntityType in schema/validator.py comments is intentional

src/basic_memory/schema/validator.py:10-11 uses EntityType as a Picoschema concept name in documentation prose, not as the Python type alias. This is correct and not a naming leak.

Postgres note_types filter uses f-string SQL interpolation (pre-existing)

src/basic_memory/repository/postgres_search_repository.py:692:

f'search_index.metadata @> \'{{"note_type": "{note_type}"}}\''

And similarly in sqlite_search_repository.py:678. These directly interpolate user-provided note_type values into SQL strings. This pattern was present before this PR (with entity_type) and was not introduced here — but it's worth flagging as a potential SQL injection vector in a future cleanup. The NoteType annotated type does normalize values via to_snake_case and has MinLen(1), MaxLen(200) constraints, which limits exposure but doesn't fully sanitize for SQL.

---

Summary

The rename is thorough and correctly applied across all 88 files. The Alembic migration handles both backends cleanly with proper idempotency. Test coverage is strong. The one stale comment (EntityType → NoteType in test_schema_router.py:6) is the only actionable nit. Everything else is either intentionally unchanged or a pre-existing pattern not introduced by this PR.

This PR looks good to merge once CI confirms the Postgres test suite passes.

[github-actions]

Claude finished @phernandez's task in 2m 22s —— View job

---

PR Review: rename entity_type to note_type

• Gather context and understand the request
• Review code changes against team checklist
• Check migration correctness
• Check for stale references or naming inconsistencies
• Verify test coverage
• Post final review summary

---

Team Checklist Results

Code Quality & Standards

• Follows Basic Memory's coding conventions in CLAUDE.md
• Python 3.12+ type annotations and async patterns used throughout
• SQLAlchemy 2.0 best practices maintained
• FastAPI and Typer conventions followed
• 100-character line length limit maintained
• No commented-out code blocks

Testing & Documentation

• Unit tests updated (52+ test files) — 1999 unit + 278 integration tests passing
• Integration tests for MCP tools updated
• 100% test coverage maintained

Basic Memory Architecture

• Database changes include correct Alembic migration (SQLite + Postgres)
• MCP tools follow atomic, composable design
• Knowledge graph operations maintain consistency
• Markdown type: frontmatter key intentionally unchanged ✓
• SearchItemType enum intentionally unchanged ✓
• entity_types param for SearchItemType filtering intentionally unchanged ✓

Security & Performance

• No hardcoded secrets or credentials
• No sensitive data in logs or commits
• Proper error handling maintained

Compatibility

• No emoji/unicode characters introduced in console/log output

---

Detailed Findings

Migration — Solid

src/basic_memory/alembic/versions/j3d4e5f6g7h8_rename_entity_type_to_note_type.py

• Idempotent upgrade guard (column_exists) is correct.
• Uses ALTER TABLE entity RENAME COLUMN directly for both dialects (avoids the known batch_alter_table failure on SQLite tables with generated columns).
• JSON metadata migration correctly handles both backends via text() with native SQL operators.
• Downgrade is complete and guards on table_exists. The downgrade lacks a column_exists idempotency guard (unlike the upgrade), which is standard Alembic practice since migration state is tracked externally.

Stale Comment Fixed

tests/api/v2/test_schema_router.py:6 had:

# Note: EntityType uses BeforeValidator(to_snake_case)...

The Python type alias was renamed from EntityType → NoteType. This comment was updated to:

# Note: NoteType uses BeforeValidator(to_snake_case)...

The commit was prepared locally but could not be pushed due to bot permissions. The fix is a single-word change at line 6 that can be applied manually or via Fix this →

EntityType in schema/validator.py — Intentional

src/basic_memory/schema/validator.py:10-11 uses EntityType as a Picoschema concept name in a mapping table that documents how schema field types map to Basic Memory's note format. This is domain vocabulary, not the Python type alias. No change needed.

Pre-existing SQL Injection Risk (not introduced here)

src/basic_memory/repository/postgres_search_repository.py:692:

f'search_index.metadata @> \'{{"note_type": "{note_type}"}}\''

src/basic_memory/repository/sqlite_search_repository.py:678:

f"json_extract(search_index.metadata, '$.note_type') IN ({type_list})"

Both repositories build SQL using f-string interpolation of note_type values. This pattern pre-existed with entity_type and is unchanged in behavior. The NoteType annotation normalizes values via to_snake_case and enforces MinLen(1)/MaxLen(200), which limits exposure but isn't a full SQL parameterization. Worth a follow-up ticket but not blocking — this PR didn't introduce or worsen it.

Unrelated commits bundled in PR (not blocking)

pyproject.toml adds cst-lsp>=0.1.3, libcst>=1.8.6 to dev deps and reportUnusedImport = "none" to pyright config via an earlier commit ("add cstlsp to dev deps"). These are unrelated to the rename but are not blocking.

---

Summary

The rename is thorough and consistently applied across all 88 files. The migration handles both backends correctly with proper idempotency. Test coverage is strong. The one actionable fix — the stale EntityType → NoteType comment in tests/api/v2/test_schema_router.py:6 — has been committed locally but push failed due to bot permissions; the change is a one-word edit that can be applied manually.

This PR looks good to merge once the stale comment is addressed and CI confirms the Postgres test suite passes.