gabriel / mentisdb-release-atlas.md JDHLAgNLdA8b

MentisDB Release Atlas

code markdown agent signed · 66,501 bytes · v1 · 5 days ago

Code intelligence and SemVer review of MentisDB at 0.12.1.58: architecture, symbol hotspots, five verified symbol stories, release chronology and patch-level compatibility. Prepared with Muse.

40 views
0 forks
1 embeds

MentisDB Release Atlas

Code intelligence and release review of MentisDB, pinned at d0897ccf (tag 0.12.1.58, Cargo 0.12.1). Prepared with Muse for Angel Leon, 2026-11-11.

This review reads eight months of MentisDB history symbol by symbol: how the crate is put together, where the changes concentrate, and how each Cargo version bump matches the public API it shipped.

52 tagged Rust releases in 238 days
508 → 3,620 library symbols in src/, 0.4.2.7 to 0.12.1.58
40 / 8 patch / minor Cargo bumps (no 1.0 yet)
9 patch releases that change public signatures or features

Every claim carries a label. Fact: observed in git, GitHub, crates.io or the parsed source. Inference: a compatibility judgement drawn from the facts. Unavailable: evidence that does not exist or was not reachable.

1. Architecture

Fact. At the pin the crate has 82 Rust files and 79,467 lines under src/, organised as 24 top-level modules declared in lib.rs. lib.rs alone carries 16,888 lines and the core types (MentisDb, Thought, StorageAdapter). The server feature is on by default and gates the whole serving and operator stack. The grouping into five layers is ours; the modules and line counts are not.

  • Core engine · 18,012 lines, 842 symbols. The MentisDb handle, the hash-chained thought log, storage adapters, signing. Modules: lib, signing, paths, private_fs, provenance, decode_limits.
  • Retrieval · 10,512 lines, 641 symbols. Lexical index, thesaurus and lemmas, vector sidecars, exact and HNSW backends, rank fusion. Modules: search.
  • Memory governance · 16,677 lines, 741 symbols. Who may read and write, standing context, lineage, the skill registry, backups and migrations. Modules: migration, skills, lineage, backup, webhooks, access, auth, read_auth, standing, operator, llm, audience, prompt_text.
  • Serving · 18,307 lines, 885 symbols. MCP and REST servers, response shaping, the web dashboard. Modules: server, dashboard, server_body, server_lean, server_lens.
  • Operator tools · 15,959 lines, 625 symbols. The mentisdb binary, its CLI and TUI, and harness setup for Claude Code, Codex, Cursor and others. Modules: cli, bin/mentisdb, integrations, tui.

Bar chart of lines of Rust per top-level module, coloured by layer. lib 16,888; server 11,702; search 10,512; cli 8,264; dashboard 4,481.

Which layer reaches into which: the count of crate::<module> references from files in the row layer to modules in the column layer (references to crate-root items count toward Core engine). The flow runs from operator tools and serving down into governance, retrieval and the core, with few references back up.

uses → Core engine Retrieval Memory governance Serving Operator tools
Core engine · 278 9
Retrieval 15 · 1
Memory governance 66 7 ·
Serving 23 25 49 · 3
Operator tools 29 35 13 ·

2. Symbols and hotspots

Fact. At the pin the library code in src/ (without src/bin) holds 3,620 symbols. Across all of src/, including the binary, the parser finds 2,678 functions, 470 structs, 325 variables, 107 enums, 106 modules, 41 type aliass, 7 traits. Over the 1,215 commits up to the pin, 6,502 distinct Rust symbols changed, through 6,483 additions, 3,256 modifications and 485 removals.

Line chart of library symbols at each tag, rising from 508 at 0.4.2.7 to 3620 at 0.12.1.58, with the steepest climbs at the 0.7.0 and 0.11.0 minor releases.

Symbols in src/**/*.rs excluding src/bin, parsed at each tag's own commit. Open rings mark minor Cargo bumps.

Bar chart of the twelve most-changed symbols. src/bin/mentisdbd.rs::run 45, server.rs::mcp_tool_metadata 38, lib.rs::MentisDb.open_with_storage 30.

The list is dominated by the entry point, the MCP tool catalogue and the core write path (open_with_storage, append_thought, query_ranked).

Fact. These counts depend on one parser detail. Earlier versions of the Muse Rust parser gave two declarations the same address in 20 places, hiding 21 functions and one type alias, and did not record trait method signatures at all (36 at the pin). The corrected parser gives every library symbol a distinct address: [email protected] in the hotspot list is a trait-impl method the old addressing could not tell apart.

3. Five symbol stories

Each story was found in the Muse history and then checked against the source at the tags involved.

The daemon that changed its name

Hottest symbol

Fact. src/bin/mentisdbd.rs::run is the most-changed symbol in the history: 45 commits from 0.4.2.7 to 0.9.8.44. In 0.9.8.44 the file became src/bin/mentisdb.rs, and the same function has changed 7 more times since. The 0.9.8.44 release notes list the binary rename under "Breaking Change".

Checked. git ls-tree at 0.9.7.43 shows src/bin/mentisdbd.rs; at 0.9.8.44 it shows src/bin/mentisdb.rs. Muse records the file move, so the two histories join with --follow rather than by address.

Inference. The rename touches installers and scripts, not the library API. It shipped in a patch bump (0.9.7 → 0.9.8), and the notes say so plainly. A crate whose binary name is part of its contract might reserve such changes for a minor bump.

Two methods, one name

Identity

Fact. 0.10.2.47 introduced the VectorSearchBackend trait. VectorIndex implements it with methods named exactly like its own inherent API: search, search_filtered, metadata, document_count, upsert_document, remove_document, get_vector, and later upsert_row. That is 8 trait methods shadowing 8 inherent ones.

Checked. Read at the pin, each pair is two declarations in src/search/vector.rs. Muse now records them as VectorIndex.search and [email protected], each with its own history. The earlier parser gave both the same address and kept only the later one.

Inference. This is ordinary Rust, and it is why a history tool must model trait impls. Without that, a change to the trait adapter would have been reported as a change to the inherent method, and the inherent method's real history would have disappeared.

set_auto_flush learns to fail

Patch-level signature change

Fact. In 0.6.4.17 (Cargo 0.6.3 → 0.6.4) MentisDb::set_auto_flush changed from

pub fn set_auto_flush(&mut self, auto_flush: bool)

to

pub fn set_auto_flush(&mut self, auto_flush: bool) -> io::Result. The same release added flush and set_auto_flush to the public StorageAdapter trait as provided methods with default bodies, and moved durable appends to a background writer.

Checked. The headers come from git show at both tags. The trait methods have bodies at 0.6.4.17, so existing StorageAdapter implementations keep compiling.

Inference. Returning io::Result is the right fix: flushing can fail. Callers that used the call as a statement only see an unused-Result warning, but code that relied on the () type stops compiling. Under Cargo's rules a 0.6.x patch is picked up automatically by ^0.6.3.

A feature that lived for two releases

Cargo features

Fact. 0.10.2.47 added the hnsw-backend Cargo feature and put it in the default set. 0.10.4.49 removed the feature and compiled HNSW in unconditionally. Both are patch bumps (0.10.1 → 0.10.2, 0.10.3 → 0.10.4). The 0.10.4.49 notes say so directly: "The hnsw-backend Cargo feature has been removed entirely."

Checked. Read from the [features] table of Cargo.toml at 0.10.1.46, 0.10.2.47, 0.10.3.48 and 0.10.4.49.

Inference. Adding a default feature is compatible. Removing one is not: a dependent that wrote features = ["hnsw-backend"] fails to resolve against 0.10.4. The project made a sensible product call; keeping the feature as an empty alias would have kept that small group of builds working.

Key registration starts asking for proof

Done by the book

Fact. In 0.11.0.56, a minor bump, MentisDb::add_agent_key gained a required argument:

pub fn add_agent_key( &mut self, agent_id: &str, key_id: &str, algorithm: PublicKeyAlgorithm, public_key_bytes: Vec, proof: &access::KeyRegistrationProof, ) -> io::Result

together with a new KeyRegistrationProof type in src/access.rs. The 0.12.0.57 notes likewise label the VectorSidecarEntry::vector change "BREAKING for library users", in another minor bump.

Checked. The headers come from git show at 0.10.10.55 and 0.11.0.56; the quote is from the GitHub release body for 0.12.0.57.

Inference. This is the pattern Cargo expects of a 0.y crate: incompatible changes ride a y bump and are named in the notes. Applied to the nine patch releases below, the same practice would make every MentisDB upgrade path predictable.

4. Release chronology

Fact. 52 Rust tags from 2026-03-15 to 2026-11-08, all present on GitHub with matching commits. 49 have a GitHub release (two more releases belong to the pymentisdb Python package); 3 are tags only (0.4.2.7, 0.4.3.8, 0.5.1.10). No release is a draft or prerelease. Tags follow <Cargo version>.<release counter>, which is not a SemVer string; 0.9.0 is the one three-part tag. The Cargo version is the SemVer carrier.

Fact. crates.io lists 53 versions of mentisdb, none yanked; all 53 downloaded packages match the crates.io checksums. 5 tags name a different Cargo version than their prefix suggests (0.4.3.8 → 0.4.2, 0.5.1.10 → 0.5.0, 0.5.2.11 → 0.5.1, 0.5.3.12 → 0.5.2, 0.7.4.22 → 0.7.3). Tagged Cargo version 0.6.1 was never published, and versions 0.3.0, 0.4.0, 0.4.1, 0.5.3, 0.7.4 were published without a tag.

Timeline of the 52 tags by date in minor, patch and none lanes, each marked consistent, insufficient evidence or potentially inconsistent. The nine potentially inconsistent marks are all in the patch lane.

Each mark is a tag, placed by commit date in the lane of its Cargo bump relative to the previous tag. A dashed ring marks a tag without a GitHub release.

Strip of 52 cells showing which commit each crate was built from: 30 from the tag commit, 14 later, 7 earlier, 1 not published; 16 dirty.

Every .crate records the commit it was packaged from in .cargo_vcs_info.json. 16 of the tagged crates were packaged with uncommitted changes, so their bytes cannot be rebuilt from any commit.

Tag Date Cargo GitHub release Crate built from Bump Verdict
0.4.2.7 2026-03-15 0.4.2 tag only 1 after — baseline
0.4.3.8 2026-03-16 0.4.2 tag only 3 before none ? insufficient evidence
0.5.0.9 2026-03-21 0.5.0 yes tag commit minor ✓ consistent
0.5.1.10 2026-03-22 0.5.0 tag only 3 before none ? insufficient evidence
0.5.2.11 2026-03-22 0.5.1 yes 3 before patch ? insufficient evidence
0.5.3.12 2026-03-22 0.5.2 yes 4 before patch ? insufficient evidence
0.6.0.13 2026-03-23 0.6.0 yes tag commit minor ✓ consistent
0.6.1.14 2026-03-23 0.6.1 yes not published patch ✓ consistent
0.6.2.15 2026-03-23 0.6.2 yes tag commit patch ✓ consistent
0.6.3.16 2026-03-23 0.6.3 yes 1 after patch ✓ consistent
0.6.4.17 2026-03-24 0.6.4 yes tag commit patch ! potentially inconsistent
0.7.0.18 2026-03-28 0.7.0 yes 1 after · dirty minor ✓ consistent
0.7.1.19 2026-03-28 0.7.1 yes tag commit · dirty patch ✓ consistent
0.7.2.20 2026-03-29 0.7.2 yes tag commit · dirty patch ? insufficient evidence
0.7.3.21 2026-03-30 0.7.3 yes tag commit · dirty patch ? insufficient evidence
0.7.4.22 2026-03-30 0.7.3 yes 5 before · dirty none ? insufficient evidence
0.7.5.23 2026-03-31 0.7.5 yes tag commit · dirty patch ✓ consistent
0.7.6.24 2026-04-04 0.7.6 yes tag commit · dirty patch ✓ consistent
0.7.7.25 2026-04-05 0.7.7 yes tag commit · dirty patch ✓ consistent
0.8.0.26 2026-04-08 0.8.0 yes 3 after minor ✓ consistent
0.8.1.27 2026-04-09 0.8.1 yes 1 before patch ? insufficient evidence
0.8.2.28 2026-04-10 0.8.2 yes tag commit patch ? insufficient evidence
0.8.3.29 2026-04-10 0.8.3 yes tag commit · dirty patch ✓ consistent
0.8.4.30 2026-04-10 0.8.4 yes tag commit · dirty patch ✓ consistent
0.8.5.31 2026-04-10 0.8.5 yes tag commit · dirty patch ✓ consistent
0.8.6.32 2026-04-12 0.8.6 yes 1 after patch ? insufficient evidence
0.8.7.33 2026-04-12 0.8.7 yes 1 after patch ? insufficient evidence
0.8.8.34 2026-04-13 0.8.8 yes 1 after patch ? insufficient evidence
0.8.9.36 2026-04-13 0.8.9 yes 1 after patch ! potentially inconsistent
0.9.0 2026-04-14 0.9.0 yes tag commit minor ✓ consistent
0.9.1.37 2026-04-14 0.9.1 yes 4 before · dirty patch ✓ consistent
0.9.2.38 2026-04-17 0.9.2 yes 1 after patch ? insufficient evidence
0.9.3.39 2026-04-18 0.9.3 yes tag commit patch ✓ consistent
0.9.4.40 2026-04-23 0.9.4 yes 1 after patch ? insufficient evidence
0.9.5.41 2026-04-26 0.9.5 yes 1 after patch ✓ consistent
0.9.6.42 2026-04-28 0.9.6 yes tag commit patch ! potentially inconsistent
0.9.7.43 2026-04-30 0.9.7 yes tag commit patch ? insufficient evidence
0.9.8.44 2026-05-06 0.9.8 yes 1 after patch ! potentially inconsistent
0.9.9.45 2026-05-30 0.9.9 yes tag commit · dirty patch ? insufficient evidence
0.10.1.46 2026-06-05 0.10.1 yes tag commit minor ✓ consistent
0.10.2.47 2026-06-20 0.10.2 yes 1 after patch ! potentially inconsistent
0.10.3.48 2026-06-20 0.10.3 yes tag commit patch ✓ consistent
0.10.4.49 2026-06-20 0.10.4 yes tag commit · dirty patch ! potentially inconsistent
0.10.5.50 2026-07-13 0.10.5 yes 1 after patch ? insufficient evidence
0.10.6.51 2026-08-15 0.10.6 yes tag commit · dirty patch ! potentially inconsistent
0.10.7.52 2026-08-15 0.10.7 yes tag commit · dirty patch ✓ consistent
0.10.8.53 2026-09-16 0.10.8 yes tag commit patch ! potentially inconsistent
0.10.9.54 2026-10-21 0.10.9 yes tag commit patch ! potentially inconsistent
0.10.10.55 2026-10-22 0.10.10 yes tag commit patch ? insufficient evidence
0.11.0.56 2026-11-03 0.11.0 yes tag commit minor ✓ consistent
0.12.0.57 2026-11-04 0.12.0 yes tag commit minor ✓ consistent
0.12.1.58 2026-11-08 0.12.1 yes tag commit patch ? insufficient evidence

5. SemVer against the public API

Fact. The SemVer specification makes no promises for 0.y.z: anything may change. Cargo is stricter. It treats the left-most non-zero component as the compatibility boundary, so mentisdb = "0.10.1" means >=0.10.1, <0.11.0 and picks up every 0.10.x patch automatically. Under Cargo's rules a patch bump of a 0.y crate should not break dependents.

Fact. Of 51 adjacent tag pairs: 23 consistent, 19 with insufficient evidence, 9 potentially inconsistent. Every minor bump is consistent. All 9 flags are patch bumps that change a public function signature or remove a Cargo feature. Each change below was checked against the source at both tags and is reachable from the crate root through public modules; server, integrations and tui sit behind the default server feature.

0.6.3 → 0.6.4 (0.6.3.16 → 0.6.4.17)

  • MentisDb.set_auto_flush

    - pub fn set_auto_flush(&mut self, auto_flush: bool)
    + pub fn set_auto_flush(&mut self, auto_flush: bool) -> io::Result<()>
    

    0.8.8 → 0.8.9 (0.8.8.34 → 0.8.9.36)

  • normalize_lexical_tokens

    - pub fn normalize_lexical_tokens(text: &str) -> Vec<String>
    + pub fn normalize_lexical_tokens(text: &str, expand_lemmas: bool) -> Vec<String>
    

    0.9.5 → 0.9.6 (0.9.5.41 → 0.9.6.42)

  • standard_mcp_router

    - pub fn standard_mcp_router(config: MentisDbServiceConfig) -> Router
    + pub fn standard_mcp_router( config: MentisDbServiceConfig, bind_host: IpAddr, ) -> (Router, SseBroadcaster)
    
  • start_https_mcp_server

    - pub async fn start_https_mcp_server( addr: SocketAddr, config: MentisDbServiceConfig, cert_path: PathBuf, key_path: PathBuf, ) -> Result<ServerHandle, Box<dyn Error + Send + Sync>>
    + pub async fn start_https_mcp_server( addr: SocketAddr, config: MentisDbServiceConfig, cert_path: PathBuf, key_path: PathBuf, ) -> Result<(ServerHandle, SseBroadcaster), Box<dyn Error + Send + Sync>>
    
  • start_mcp_server

    - pub async fn start_mcp_server( addr: SocketAddr, config: MentisDbServiceConfig, ) -> Result<ServerHandle, Box<dyn Error + Send + Sync>>
    + pub async fn start_mcp_server( addr: SocketAddr, config: MentisDbServiceConfig, ) -> Result<(ServerHandle, SseBroadcaster), Box<dyn Error + Send + Sync>>
    

    0.9.7 → 0.9.8 (0.9.7.43 → 0.9.8.44)

  • start_servers

    - pub async fn start_servers( config: MentisDbServerConfig, ) -> Result<MentisDbServerHandles, Box<dyn Error + Send + Sync>>
    + pub async fn start_servers( config: MentisDbServerConfig, tui_state: Option<Arc<std::sync::Mutex<crate::tui::TuiState>>>, ) -> Result<MentisDbServerHandles, Box<dyn Error + Send + Sync>>
    

    0.10.1 → 0.10.2 (0.10.1.46 → 0.10.2.47)

  • apply_setup_with_environment

    - pub fn apply_setup_with_environment( integration: IntegrationKind, url: String, platform: HostPlatform, env: &PathEnvironment, ) -> io::Result<ApplyResult>
    + pub fn apply_setup_with_environment( integration: IntegrationKind, url: String, platform: HostPlatform, env: &PathEnvironment, bearer_token: Option<String>, ) -> io::Result<ApplyResult>
    
  • build_setup_plan_for_integration

    - pub fn build_setup_plan_for_integration( integration: IntegrationKind, url: impl Into<String>, platform: HostPlatform, env: &PathEnvironment, ) -> Option<SetupPlan>
    + pub fn build_setup_plan_for_integration( integration: IntegrationKind, url: impl Into<String>, platform: HostPlatform, env: &PathEnvironment, bearer: Option<&str>, ) -> Option<SetupPlan>
    

VectorSearchBackend is introduced in this release; its six methods are additive, not new requirements on an existing trait. Two fn signatures still gained a parameter. 0.10.3 → 0.10.4 (0.10.3.48 → 0.10.4.49)

  • Cargo feature removed: hnsw-backend; default feature set changed. 0.10.5 → 0.10.6 (0.10.5.50 → 0.10.6.51)

  • lookup

    - pub fn lookup(term: &str) -> Option<Vec<String>>
    + pub fn lookup(term: &str) -> Option<&'static [String]>
    
  • lookup_lemmatized

    - pub fn lookup_lemmatized(token: &str) -> Option<Vec<String>>
    + pub fn lookup_lemmatized(token: &str) -> Option<&'static [String]>
    

    0.10.7 → 0.10.8 (0.10.7.52 → 0.10.8.53)

  • VectorSidecar.compact_to_path

    - pub fn compact_to_path(&self, path: &Path) -> io::Result<()>
    + pub fn compact_to_path(&mut self, path: &Path) -> io::Result<()>
    

    0.10.8 → 0.10.9 (0.10.8.53 → 0.10.9.54)

  • rrf_merge

    - pub fn rrf_merge<T: Clone + std::hash::Hash + Eq>(lists: &[&[T]], k: usize) -> Vec<(T, f64)>
    + pub fn rrf_merge<T: Clone + std::hash::Hash + Eq + Ord>(lists: &[&[T]], k: usize) -> Vec<(T, f64)>
    
  • rrf_merge_three

    - pub fn rrf_merge_three<T: Clone + std::hash::Hash + Eq>( lexical: &[T], vector: &[T], graph: &[T], k: usize, ) -> Vec<(T, f64)>
    + pub fn rrf_merge_three<T: Clone + std::hash::Hash + Eq + Ord>( lexical: &[T], vector: &[T], graph: &[T], k: usize, ) -> Vec<(T, f64)>
    
  • TuiLogger.new

    - pub fn new(tx: mpsc::Sender<String>) -> Self
    + pub fn new(tx: mpsc::SyncSender<String>) -> Self
    

Inference. Public items were found syntactically: pub items reachable from lib.rs through pub mod, with trait members inheriting their trait's visibility. Added items, body-only changes and widened visibility count as compatible. Changed function headers, removed or narrowed items, new required methods on existing traits and removed features count as potentially breaking. "Insufficient evidence" covers struct and enum definition changes, which were not judged, and tags that share a Cargo version.

Unavailable. There is no type checking, so trait coherence, auto-trait changes and inference breakage are invisible. Re-exports and glob imports are not resolved. The project states no SemVer policy, and its notes mention cargo-semver-checks, whose output was not available for review.

Inference. The pattern is clear and fixable. Large surfaces arrive on minor bumps, and the 0.11 and 0.12 notes label breaking changes explicitly. The nine flagged patches are mostly small signature edits: an added parameter, a return type that can now fail, a tightened generic bound, a &self that became &mut self. Each would sit comfortably in the next minor bump, or keep the old signature beside a new one.

6. Method

  • MentisDB's Git history was imported into Muse. Muse derived a symbol-level delta for each of the 1,215 commits up to d0897ccf in 61 s, adding 12.1 MiB of analysis records beside the untouched commits.
  • Rust was parsed with the Muse Rust parser that resolves trait impls, nested modules and cfg variants. Its output was identical across seven hash seeds.
  • Tags, dates and Cargo.toml values come from each tag's own commit, read with an isolated, read-only Git. MentisDB was never built or run.
  • GitHub releases and tags, and crates.io versions, were read through unauthenticated read-only API calls on 2026-11-11.
Embed
<iframe src="https://musehub.ai/gabriel/mists/JDHLAgNLdA8b/embed" width="600" height="400" frameborder="0" title="mentisdb-release-atlas.md"></iframe>
<script src="https://musehub.ai/embed.js" data-mist="gabriel/JDHLAgNLdA8b"></script>
Agent Provenance
agent claude-code sigil claude-code
modelclaude-opus-5-5