Crate memstead_git_branch

Expand description

Git-branch storage backend for Memstead — sibling to the folder and archive backends in memstead-base. Implements memstead_base::backend::MemBackend over a multi-root mem-repo-git repository: each mem lives on its own branch (refs/heads/<mem> for flat layouts, refs/heads/<path>/<mem> for hierarchical), entities are blobs in the per-mem tree, provenance is encoded in commit objects (subject = mutation kind + entity, trailer block = actor / client / tool, body paragraph = agent note). Workspace-level state — per-mem config, schema bodies — lives on the __MEMSTEAD umbrella ref.

§Crate role

This crate is one of three storage backends. The workspace concept itself, the unified Engine, the entity loader, the schema registry, and the runtime validator all live in memstead-base. This crate’s exports are:

storage::git_tree::GitTreeMemWriter — the memstead_base::backend::MemBackend implementation that buffers mutations and applies them via gix::object::tree::Editor against the per-mem branch.
storage::instantiate_full_backend — the memstead_base::BackendFactory full consumers install on the unified Engine at boot (workspace_store::engine_from_workspace_root) so the factory can materialise git-branch backends in addition to folder + archive.
workspace_store::engine_from_workspace_root — full-flavour workspace boot path that loads the two-layer file adapter (.memstead/workspace.toml + .memstead/state/mounts.json).
Full-side helpers consumed by the unified surface: mem_repo_config::commit_config_at_gitdir (per-mem config writes into __MEMSTEAD for git-branch mounts), ops::agent_notes::agent_notes_since, ops::changes::changes_since, and ops::export::export_mem (consumed through the trait or directly by memstead_base::Engine).

Built only with the mem-repo Cargo feature on memstead-mcp / memstead-cli (or via the workspace-level --features mem-repo). Lean builds skip this crate entirely; the lean MCP / CLI binaries link only memstead-base.

Re-exports§

pub use ops::changes::ChangesReport;
pub use vcs::Vcs;
pub use vcs::VcsError;

Modules§

chunking: Token-budget chunking for large MCP responses.
discover: Branch enumeration for the workspace’s mem-repo/.git/.
entity: Re-export shim over memstead_base::entity plus the git-touching git_tree_source submodule that stays in this crate.
graph: Graph algorithms — BFS traversal, community detection, neighborhood queries.
mem: Multi-mem routing, visibility filtering, mem config.
mem_cache: Read-mem cache resolution, published-config reads, and the install-to-cache side effect.
mem_repo_config: Read mem configs from mem-repo-git:__MEMSTEAD:mems/<path>/<leaf>/config.json.
mem_repo_schemas: Read workspace-level schemas from the unified __MEMSTEAD ref.
ops: Re-export shim over memstead_base::ops (request/response types, WarningHint, plus the gix-free health and search submodules) plus the git-touching operation submodules that stay in this crate.
render: Markdown rendering of Engine result types.
search_index: Per-mem tantivy search indexes.
storage: Re-export shim over memstead_base::storage (the MemWriter trait and MemWriterError) plus the git-tree adapter that stays in this crate.
storage_memstead: Unified __MEMSTEAD ref — schemas + per-mem configs in one tree.
store: In-memory graph store. Dumb data structure — no validation, no side effects. All mutations go through Engine methods.
validator: Strict ingress validator for sealed .mem archives.
vcs: Per-mem version control via gix. Each mem owns a gix repository whose gitdir and worktree are resolved from the mem’s config at Engine::init time — isolated from any outer project repo and from the developer’s ~/.gitconfig.
workspace_root: Workspace-root utilities. Today’s only consumer is the memstead_health OUTER_REPO_NOT_IGNORING_MEM_REPO warning surfaced by the MCP layer: when the workspace is embedded inside another git repository, the mem-repo-git directory must be excluded by the outer repo’s .gitignore to avoid the gitlink trap.
workspace_store: Full-flavour workspace boot helper.

Structs§

AgentNotesReport: Walked output of agent_notes_since. head echoes the resolved branch tip so callers record it as the next polling cursor without a follow-up memstead_health round-trip. memstead_ref carries the workspace-level __MEMSTEAD ref tip (unified schemas + per-mem configs) so consumers — today the outer-repo auto-commit cursor block — anchor it alongside the per-mem head without a second round-trip. None when the workspace has not been migrated to the unified layout yet.
BatchResult: Result of an atomic batch update — all-or-nothing.
ClientId: Identity of the process speaking to the engine. For MCP, this is the clientInfo from the initialize handshake (e.g. ClientId { name: "claude-code", version: "2.1.0" }). For CLI-direct mutations, the crate populates it with its own name and version.
ClusterInfo: Info about a single community cluster.
CommitContext: Provenance bundle for a single commit. Produced at the caller boundary (memstead-mcp tool handler, memstead-cli subcommand, engine-internal drift flush) and threaded through to the VCS commit path.
CommitNote: One commit’s worth of structured agent-note state. Fields are populated best-effort: a body that doesn’t match the memstead: <verb> <id> subject shape leaves tool_verb / entity_id None; absent trailers leave the corresponding fields None. Callers branch on actor for agent-vs-external classification.
ContextResult: Context around an entity — neighbors, community, related entities.
CreateArgs: Arguments for creating an entity.
CreateResult: Result of a create operation.
DeleteResult: Result of a delete operation.
Edge: Edge in the graph.
Entity: A parsed entity with metadata, sections, and relationships.
EntityId: Unique entity identifier: mem--entity-path.
ExportResult: Export result.
Facets: Fixed set of facet dimensions computed over the unpaginated hit set. Tier 1 freezes the dimensions; extend later only if empirical use demands it. Zero-count entries are excluded to keep the payload small.
HealthReport: Health check result for one entity.
HealthSummary: Aggregated health report for the whole graph.
InEdge: Incoming edge — stored in in_edges for efficient reverse lookups.
ListResult: List result with token totals.
LouvainOutput: Output of Louvain community detection: clusters, reverse lookup, and quality metrics. Computed on demand by Engine::communities() and cached in an in-memory memo that is invalidated whenever the graph mutates (see Engine::invalidate_communities).
MemExportResult: Result of a .mem mem-archive export.
MemInit: Description of a mem discovered on a git-branch backend. Produced by mem_repo_config::mem_init_from_branch for the macOS discover_mems UniFFI helper, which seeds the UI’s mem list before the engine itself is constructed.
MemRouterSnapshot: Mem configuration for the engine runtime — cloneable snapshot.
ModifiedMetadata: Metadata-level mutations applied by a single memstead_update call. Same empty-vec-omit convention as ModifiedSections; auto-timestamp metadata fields written by the engine are NOT surfaced here (they are engine-driven, not user-driven — the caller has nothing to react to).
ModifiedSections: Section-level mutations applied by a single memstead_update call. Each vec lists the section keys that landed in that mutation mode. Empty inner vecs are serde-omitted so the wire stays quiet; the struct itself always serialises so the outer modified_sections key is a stable shape regardless of what the call actually touched.
ParseResult: Result of parsing a markdown file. Includes the entity, extracted inline links, and parse-time warnings (e.g. duplicate section headings).
Query: Flat query shape for full-text search. Four optional fields, all combined with implicit AND across fields.
RelateArg: Arguments for a relate/unrelate operation.
RelateResult: Result of a relate operation.
Relationship: A declared relationship in the Relationships section.
ReloadReport: Per-mem reload outcome — produced by [Engine::reload_one_mem] and surfaced verbatim in the memstead_reload MCP tool’s response when an explicit operator-triggered reload runs against a single mem. Auto-reloads on the read path consume this internally and emit a WarningHint::MemReloaded (which carries mem, old_head, new_head, entities_loaded — the diff list is intentionally omitted from the lean warning payload; agents that need it call memstead_changes_since themselves with the supplied old_head).
ReloadResult
RenameResult: Result of a rename operation.
SearchHit: A search result hit.
SearchResult: Search result with metadata.
SearchScope: Scope filters for search and list operations.
Store: The graph store. Three maps: nodes, outgoing edges, incoming edges.
UpdateArgs: Arguments for updating an entity.
UpdateResult: Result of an update operation.

Enums§

Actor: Caller categories for the Actor: trailer and for picking an author signature. Agent and Cli get their author from the paired ClientId when one is present; External always uses the synthetic external <external@memstead.io> identity (no client is known); Unknown falls back to the committer identity.
ChangeEnvelope: Single delta entry between two snapshots. Renamed collapses what would otherwise appear as a Removed + Added pair so agents see one semantic event per filesystem rename.
EdgeSource: Where an edge was declared. Under the alias model every authored edge is Explicit (an entry in the auto-managed ## Relationships section); Hierarchy is a derived view over PART_OF rather than an authoring channel; BodyLink is engine-emitted from a body wiki-link via the alias-synthesis pass (rel-type equals the source schema’s alias_target_rel_type pointer).
MemExportError
MemOrigin: Provenance record attached to every writable-mem registration.
MetadataValue: A metadata value with type coercion matching the JS parser behavior.
WarningHint: Typed non-fatal issue surfaced from engine operations. Serialises as the uniform { code, message, details } envelope so a generic warning handler (log sink, UI, alerting) can read code + message without branching on variant. Display renders the agent-facing text, reachable via WarningHint::message; per-variant structured fields land under details, their shape keyed by code.

Constants§

EMPTY_TREE_SHA: Canonical git empty-tree hash. Callers without a prior cursor pass this to get “every entity in the current state as added”. Both the git-branch backend (special-cased to bypass rev_parse) and any future folder-backend implementation honour the same sentinel.
RENAME_SIMILARITY_DEFAULT: Default content-similarity threshold for rename detection (60%). Callers override per-call via changes_since’s rename_similarity parameter; the engine wrapper accepts [0.1, 1.0] and emits a LIMIT_CLAMPED warning for out-of-range values. Higher values miss edited renames; lower values risk false-positive rename pairing.
RENAME_SIMILARITY_MAX: Upper bound for rename_similarity — 1.0 means “only paired up on a byte-identical match”; above that there is no semantic meaning.
RENAME_SIMILARITY_MIN: Lower bound for rename_similarity — anything below 0.1 produces nearly-random rewrite pairing on a modest diff.

Functions§

engine_fallback_type: Engine-wide sentinel type. Used by ops that need a shared reference type at the Engine level (search, health, list) — always resolves to default@1.0.0::spec. Per-entity resolution still goes through type_by_name + schema lookup.