[delete-cloud]

Summary

• add Coding Agent semantic backend schema/scope contracts and a deterministic fake backend
• wire disabled-by-default [memory.semantic] config without retrieval integration
• add backend contract and memory-switch regression tests

Scope

• PR2 for ADR-0072 semantic tape memory
• no AgentKit storage protocol changes
• no concrete LanceDB/Chroma/Milvus/pgvector adapter
• no semantic retrieval rendering or sync/rebuild job

Verification

• UV_PYTHON=3.12 uv run pytest tests/coding_agent/test_memory_index_backend_contract.py tests/coding_agent/test_memory_switch.py tests/coding_agent/test_semantic_tape_index.py -q
• UV_PYTHON=3.12 uv run ruff check src/coding_agent/core/app.py src/coding_agent/topics/semantic_backends tests/coding_agent/test_memory_index_backend_contract.py tests/coding_agent/test_memory_switch.py
• git diff --check
• local code-review-expert gate: APPROVE_NO_P1_P2

Summary by CodeRabbit

• New Features

  • Added optional semantic memory support with configurable enablement and a built-in fake backend.
  • Semantic memory objects are now available in the app context when enabled.

• Bug Fixes

  • Improved validation for semantic memory settings, with clearer errors for invalid configuration.
  • Added safer scope handling so deletions and lookups stay limited to the intended memory scope.

• Tests

  • Expanded coverage for semantic memory configuration, backend behavior, schema changes, and scoped operations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 048cab44-a7eb-47fa-8642-004e0dfa4c94

📥 Commits

Reviewing files that changed from the base of the PR and between 8250cf4 and 4a56600.

📒 Files selected for processing (7)

• coding-agent/src/coding_agent/agent.toml
• coding-agent/src/coding_agent/core/app.py
• coding-agent/src/coding_agent/topics/semantic_backends/__init__.py
• coding-agent/src/coding_agent/topics/semantic_backends/base.py
• coding-agent/src/coding_agent/topics/semantic_backends/fake.py
• coding-agent/tests/coding_agent/test_memory_index_backend_contract.py
• coding-agent/tests/coding_agent/test_memory_switch.py

---

📝 Walkthrough

Walkthrough

A new semantic_backends package is introduced with a base contract module (SemanticIndexSchema, SemanticBackendScope, SemanticMemoryBackend protocol, source ref helpers) and a fake in-memory implementation. MemorySwitchConfig gains a SemanticMemoryConfig field parsed from [memory.semantic] TOML; create_child_pipeline() conditionally wires FakeSemanticMemoryBackend and SafeSemanticMemoryIndex into ctx_config.

Changes

Semantic Memory Backend Subsystem

Layer / File(s)	Summary
Semantic backend contracts and helpers coding-agent/src/coding_agent/topics/semantic_backends/base.py, coding-agent/src/coding_agent/topics/semantic_backends/__init__.py	Defines SemanticIndexSchema (with __post_init__ validation), SemanticSchemaMismatch, SemanticBackendScope (immutable, with scope matching), and the SemanticMemoryBackend runtime-checkable protocol. Adds normalize_source_refs, memory_hit_from_document, and internal validation helpers. Exports all public symbols via __all__.
Fake in-memory backend coding-agent/src/coding_agent/topics/semantic_backends/fake.py	Implements FakeSemanticMemoryBackend backed by a dict[SemanticDocId, _StoredDoc], supporting ensure_schema (with optional rebuild), upsert, search (token-overlap scoring), delete, list_ids (with optional scope filter), and delete_scope. Defines FAKE_SEMANTIC_INDEX_SCHEMA and internal tokenization helpers.
App config, parsing, and pipeline wiring coding-agent/src/coding_agent/core/app.py, coding-agent/src/coding_agent/agent.toml	Adds SemanticMemoryConfig dataclass and a semantic field on MemorySwitchConfig. Implements _parse_semantic_memory_config() to validate the [memory.semantic] TOML table (restricting backend to "fake"). Conditionally constructs FakeSemanticMemoryBackend and SafeSemanticMemoryIndex in create_child_pipeline() and adds them to ctx_config. Sets default [memory.semantic] in agent.toml.
Contract and integration tests coding-agent/tests/coding_agent/test_memory_index_backend_contract.py, coding-agent/tests/coding_agent/test_memory_switch.py	Contract tests cover upsert/search/delete, schema mismatch/rebuild, scope validation, scoped delete isolation, and score ordering. Memory-switch tests are updated for the new semantic defaults and expanded with cases for disabled, unknown-backend, and fake-backend semantic initialization.

Sequence Diagram(s)

sequenceDiagram
  participant AgentConfig as agent.toml / caller
  participant AppParser as _parse_semantic_memory_config
  participant SemanticMemoryConfig
  participant Pipeline as create_child_pipeline
  participant FakeSemanticMemoryBackend
  participant SafeSemanticMemoryIndex

  AgentConfig->>AppParser: [memory.semantic] table
  AppParser->>SemanticMemoryConfig: construct(enabled, backend)
  SemanticMemoryConfig-->>Pipeline: memory_cfg.semantic

  alt memory_cfg.semantic.enabled == True
    Pipeline->>FakeSemanticMemoryBackend: __init__(schema)
    Pipeline->>SafeSemanticMemoryIndex: __init__(backend)
    SafeSemanticMemoryIndex-->>Pipeline: index
    Pipeline-->>AgentConfig: ctx_config["semantic_memory_backend"] + ctx_config["semantic_memory_index"]
  else memory_cfg.semantic.enabled == False
    Pipeline-->>AgentConfig: semantic keys omitted from ctx_config
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• delete-cloud/Coding-Agent-Loop#614: Introduced MemorySwitchConfig in app.py; this PR directly extends that same class with the SemanticMemoryConfig field and parsing logic.

Poem

🐇 Hoppity-hop through memory's gate,
A semantic index, fresh and great!
Fake backends flourish, schemas align,
Scoped deletions drawn with care so fine.
The rabbit checks each source ref twice —
No stale doc escapes; that's rather nice! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the core change: adding the semantic backend contract to memory.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/semantic-backend-contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}