v0.4.0

v0.4.0

The semantic session-memory release: the session database gains an embedding
substrate and a hybrid retrieval mode behind one retrieval service, the source
install selects its Python deterministically and says so, the study-plan-architect
becomes a first-class mentor role in every harness, and OpenCode and Grok Build
join Claude Code, Kiro CLI and Codex in having both StudyLoop MCP servers
registered by the installer. A repository-wide documentation-versus-code review
(council-reviewed, test-first) made the docs, the installed prompts and the
configuration keys say what the code does.

StudyLoop 0.4.0 follows the documented source-checkout installation flow. CI
builds and installs wheel/sdist artifacts as validation evidence; this release
does not advertise GitHub or PyPI binary distribution.

Changes

Semantic session search

• Schema 48 adds message_embeddings (chunked, content-hashed) with a
  sqlite-vec sidecar index. session-maint embed fills the backlog,
  session-maint embed-check [--fix] audits alignment, studyloop doctor
  reports embeddings_alignment, and the export hook keeps vectors current.
• Every agent-facing search (session_search over MCP, session-query, the
  retrieval half of memory_search) goes through one retrieval.search
  service; natural-language queries no longer crash on FTS5 syntax.
• Hybrid mode fuses the lexical and embedding arms with unweighted Reciprocal
  Rank Fusion. It is off by default and enabled with semantic_search.hybrid: true, or for one process with STUDYLOOP_RETRIEVAL_MODE=hybrid.

Installation

• A committed .python-version (3.12) drives uv sync and uv run;
  studyloop install tools passes the same minor to every uv tool install;
  ./scripts/install.sh prints the interpreter uv resolved, installs the pinned
  3.12 through uv when no matching interpreter exists, refuses anything outside
  3.12–3.14, and reports the interpreter each tool venv received. UV_PYTHON=3.13 ./scripts/install.sh is the documented override. The nightly install workflow
  runs the real installer and checks Python 3.14 as a signal; CI asserts each
  matrix job runs the Python it names.

Mentor harnesses

• The study-plan-architect is a first-class role: one canonical persona,
  delivered by studyloop study --mode plan-architect (or studyloop plan architect) to Codex, pi and Grok Build, and installed as a native named agent
  for Claude Code, Kiro CLI and OpenCode.
• OpenCode and Grok Build get both StudyLoop MCP servers (session-db,
  studyloop) registered by studyloop install agents / doctor --fix, with the
  session-query CLI fallback still documented for every harness. pi stays
  CLI-only because it has no MCP support by design. Server names are identical in
  every harness config; studyloop-mcp and session-db-mcp are the commands.
• Grok Build sessions export automatically at session end; doctor reports
  session_export_hook_grok.

Doctor and configuration

• New checks exporter_schema and export_freshness; export hooks are pinned to
  the installed binary and logged.
• agent-session-tools honours a top-level session_db: with studyloop's
  precedence, so both packages open the same database. Doctor no longer flags
  the configuration sections the setup guide recommends; studyloop setup writes
  agents.priority rather than a dead key; the Obsidian export check verifies
  the memory directory is writable without creating it; the Kiro hook check reads
  both agent-file schemas; obsidian.filename_template is honoured.

Documentation and prompts made congruent with the code

• Six harnesses stated the same way everywhere; session-memory docs describe
  schema 48 and the retrieval modes; the CLI reference documents session-maint embed/embed-check; installed prompts instruct only commands and tools that
  exist; architecture notes point at the real modules; SECURITY.md and
  CONTRIBUTING.md use version-independent wording. Doc-contract tests now pin
  each of these to code symbols.

Release tooling

• just release-check runs the release consistency check in --pre-tag mode;
  just release-verify runs the strict form after tagging; a release note that
  is still the prepare-release skeleton fails the gate.

Verification

• just release-check (pre-tag) on the release commit; just release-verify
  after the tag.
• Full unit suite green on the release branch before the cut (6,145 passed, 15
  skipped; the release commit's own just release-check run is the gate);
  acceptance install from a fresh clone in a user-like environment
  (Homebrew Python 3.14 only, no UV_PYTHON) → exit 0, workspace and tool venvs
  on 3.12.
• Council records and evidence: reviews/2026-09-14-congruence-review/
  (git-ignored).