Skip to content

refactor(core): simplify v0.23 runtime protocols - #1164

Merged
phernandez merged 1 commit into
mainfrom
codex/v0.23-protocol-cleanup
Jul 27, 2026
Merged

refactor(core): simplify v0.23 runtime protocols#1164
phernandez merged 1 commit into
mainfrom
codex/v0.23-protocol-cleanup

Conversation

@phernandez

Copy link
Copy Markdown
Member

Why

The v0.23 indexing and semantic-search work added a large Protocol surface so the
portable runtime could serve both Basic Memory and Basic Memory Cloud. A
cross-repository audit found a smaller set of contracts that were unused,
duplicated, mutable despite representing results, or hiding ownership behind an
extra adapter.

This cleanup removes those vestiges before the release without removing any
feature or weakening a capability that Cloud consumes.

What Changed

  • Removed unused or duplicate Protocols for directory deletion, initial project
    indexing, relation scheduling, note-file cleanup, and vector synchronization.
  • Added one shared, frozen VectorSyncBatchResult and kept mutable batch
    accounting private to the semantic-vector repository operation.
  • Made structural data members read-only so frozen dataclasses and ORM-backed
    values can satisfy the same narrow contracts.
  • Removed unnecessary nominal Protocol inheritance from concrete embedding,
    reranking, SQLite, pgvector, and Milvus implementations.
  • Moved local missing-file race handling into the local storage metadata adapter
    and removed the wrapper that previously obscured that responsibility.
  • Made local frontmatter result values frozen and slotted.
  • Ignored all repository-local .codex runtime state and nested worktrees while
    allowlisting a minimal shared .codex/basic-memory.json.

There are no user-visible feature removals.

Implementation Details

src/basic_memory/runtime/vector_sync.py is now the single portable home for
the vector-sync capability and its immutable batch result. The repository
implementation uses a private accumulator and freezes counts, timings, and
failed entity IDs at the public boundary.

Property-only Protocol members are now read-only properties. Concrete providers
remain structurally compatible, but no longer inherit those Protocols
nominally; this avoids inherited property descriptors conflicting with normal
instance initialization.

LocalStorageFileMetadataSource now owns checksum lookup semantics directly. A
wrapped FileNotFoundError still means the file vanished between existence and
checksum checks, while permission and transient I/O errors continue to
propagate.

The shared Codex config contains only the coding profile and canonical
repository identifier. User project mappings and all .codex/worktrees state
remain machine-local.

Testing

Automated

  • just fast-check: passed (Ruff fix/format and ty type checking; nine
    existing Python 3.14 event-loop deprecation warnings).
  • BASIC_MEMORY_ENV=test LOGFIRE_IGNORE_NO_CONFIG=1 uv run pytest -q --no-cov tests/index/test_local_schedulers.py tests/index/test_inline_storage_event_processor.py tests/indexing/test_embedding_index_planning.py tests/indexing/test_vector_sync_planning.py tests/repository/test_semantic_vector_sync.py:
    51 passed.
  • Expanded provider/vector regression suite: 294 passed.
  • just doctor: passed the isolated file, database, indexing, vector, search,
    and status flow.
  • just fast-test: 4,969 passed and 33 skipped. The only failure was the live
    postgres-openai semantic-quality benchmark, which reached OpenAI and
    received HTTP 429 insufficient_quota.
  • AST Protocol audit: no writable Protocol attributes remain.
  • Retired-contract name scan and git diff --check: passed.

Risks / Follow-ups

  • The live OpenAI benchmark remains dependent on account quota; its failure did
    not exercise a changed local code path.
  • A broad SearchRepository split and complete cross-repository frontmatter
    result unification are intentionally deferred until after v0.23. They would
    expand release risk without simplifying this patch.

Signed-off-by: phernandez <paul@basicmachines.co>
@phernandez
phernandez merged commit db70a01 into main Jul 27, 2026
25 checks passed
@phernandez
phernandez deleted the codex/v0.23-protocol-cleanup branch July 27, 2026 18:29
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