memoweft

MemoWeft

MemoWeft is a local-first memory engine for AI applications. It keeps Evidence, derived World objects, provenance, revisions, corrections, retractions, permission state, and portable data as distinct records so a host can explain what it remembers and why.

简体中文

Package surfaces

The root npm package is the TypeScript library. The py/ project is the Python MemoWeft 2.0 implementation and contains the production Hermes provider, Trust services, Portable v4, and DSH RPC v2. The source tree also contains a Memory Experience app; that app is not embedded in the root npm tarball.

The Python distribution exposes the memoweft provider in the hermes_agent.memory_providers entry-point group. Package metadata, source manifests, and installed behavior are separate evidence layers and should be verified independently.

Install the TypeScript package

Use npm install memoweft for a published npm release. Node 24 has a built-in SQLite path; Node 20 and Node 22 use the optional better-sqlite3 driver.

The repository candidate may be newer than the latest published package. A successful local build or tarball hash does not prove registry publication.

Memory contracts

MemoWeft keeps these boundaries explicit:

• Raw user content remains exact Evidence with provenance and permissions.
• A request to forget a stored memory is not a denial of the remembered fact; formation excludes that command's item while independent factual statements remain eligible. Raw Evidence stays intact until the separate authorized forgetting flow completes; genuine factual denials still support retraction.
• A source-bound correction counts as fulfilled after a later no_change only when its applied receipt, current replacement, exact support range and stated projection agree. Other corrections, remember requests and unknown uncovered facts in that same message remain unfinished; a shared source alone is not proof of completion. The shared ledger also accepts verbatim MemoryLoop Evidence records; their prose or JSON content is never a formation-support record or proof that a correction completed.
• Stated formation propositions selected by segment or quote are derived from verbatim Evidence, preserving names, forms of address, numbers and dates. Formation payloads offer intact sentences alongside existing fine segments. A support can explicitly select sentence_id for a complete same-topic claim, or segment_id for independent clauses. These are alternative source ranges; Core never expands an unselected range and rejects overlapping selections. Named people with an explicit relationship to the user are classified as Relationship records, rather than naming-only or third-party attributes. Invalid interpretation JSON or compiler fields receive one model rewrite with the concrete compiler error before the job settles without a write. The durable model checkpoint retains the first response, error and rewrite outcome; recovery never repeats a reserved or completed rewrite. The default DSH HTTP route requests response_format: {"type": "json_object"}; Core validation still checks required fields and evidence grounding. A model no_change result after a declarative source also receives the same single, checkpointed reconsideration, with its first result retained. Event calendar dates are normalized from an unambiguous explicit numeric date in the selected source; relative or ambiguous dates retain their original time expression without a guessed occurred_at value. Reasoning-only model output is never used as an interpretation or included in rewrite feedback.
• Entity, Relationship, Event, Cognition, and Evaluation records are formal World objects.
• Confirmations can reference the preceding four permission-eligible conversation turns. The compiler validates the exact assistant proposal against its persisted message ID and keeps the user's confirmation as Evidence. Proposal references join the existing support/deletion graph; source queries expose both originals. An explicit user restatement stays verbatim and may retain a unique same-person preceding proposal as context. Assistant prose never becomes user Evidence. Importing a proposal through confirmed requires a known affirmative or an affirmative plus a complete literal value from that proposal, in both the selected span and the complete short reply. Incidental character overlap and a cropped affirmative before a denial do not qualify. Other explicit user restatements use stated; see the rules and audit. Action-directed assent such as Yes, do that. or 好 requires the selected claim itself to be an action proposal. A neighboring offer cannot confirm a factual guess; the confirmation explanation quotes only the selected claim, while provenance retains the complete original assistant turn. A short Chinese reference to an earlier action can precede explicit assent; its complete literal topic and action verb must match the selected proposal. Whole-reply denial checks still apply; the finite grammar and limits are documented in the confirmation rules.
• World-item forgetting pauses with formation_in_progress while another source in the same account is being interpreted against the current World. Preview and execution apply the same check, including an older confirmation. It does not infer or erase an unconfirmed correction source. Once formation settles, the owner obtains a new preview; an explicitly confirmed batch covering all of the in-flight job's sources can still erase them atomically and fence the late worker. Other accounts and unrelated, not-yet-started jobs are unaffected.
• Hosts bind the actual recall dependencies to assistant turns through the existing model_context_dependencies boundary field or link_interaction_dependencies. Forgetting a fact erases whole dependent interaction-context copies, transitively, without touching the original application chat. Legacy copies lacking complete dependency capture are matched within the account against full original/canonical facts (with presentation and owner-pronoun normalization), and appear in the same forget preview. Matching requires whole-clause equality and preserves word/value boundaries (York never matches Yorkshire). Content-free context identities and retained source IDs fence replay and survive Portable v4; an erased copy wins over an older live copy in either restore order. Export does no word scrubbing. This cannot revoke a standalone historical backup restored into a database that has never received the deletion state.
• Forget previews return forget_scope. Clients must retain this value with the confirmed plan and send it unchanged in payload.forget_scope on delete_evidence / delete_world_item. It binds the account, target, World revision and the affected context/commitment IDs and contents. Unrelated additions do not invalidate the confirmed set. Under the existing write lock, a changed snapshot rejects with forget_scope_changed; a legacy call that would alter contexts without a token rolls back with forget_scope_required. Re-preview and obtain a new confirmation and command ID after rejection; never silently refresh the token at execution time. forget_scope_fence: 1 advertises this contract. forget_batch: 1 additionally supports additional_targets (1–31 exact {target_kind, target_id} objects) on preview_forget and in the existing delete command payload. The primary target plus these targets share one preview, account, revision, scope token, transaction and receipt. Preview lists the combined cascade; the token binds the ordered target list as well as all affected context copies. A missing scope, changed target/context or rejected source rolls back the entire batch. Overlapping revision chains are erased once. Every explicit target's full revision chain and source set is collected before any cascade writes, so an object removed by an earlier source never causes its remaining sources or rejection checks to be skipped. Credentials from the earlier incomplete batch preview are rejected; obtain a new complete preview and confirmation. Single-target credentials are unchanged. Retain the original confirmed token; no per-target refresh or host-side queue is needed. Existing single-target calls remain unchanged. The same scope includes evidence.preceding_ai_context copies. Preview items identify them as object_kind=evidence_context, item_type=preceding_ai_context; successful receipt affected_ids includes their Evidence IDs. Context-only cleanup retains the independent raw Evidence and does not add it to the preview's source-deletion evidence_ids list. Portable erasure markers carry a content-free original context fingerprint; alternate local IDs with reused session/episode names must match that fingerprint, and all matched IDs participate in the same transitive cascade.
• Recall is deterministic for the same source snapshot and ready retrieval index, and performs no World writes. Pending explicit first-person preference quotes can also accompany first-person preference questions when the changed value does not repeat the old activity noun. They remain verbatim provisional user context, not a synthesized slot, replacement link or formal World item. This bounded fallback does not nominate third-person statements, quoted tasks or questions; the existing account, destination permission, age, size and deletion gates still apply. Once formation settles, formal recall replaces the pending quote through the existing path. Python links current, sourced self-naming claims and accepted aliases to the same person even when an earlier neutral name remains canonical; only current, destination-readable alias provenance can establish this link. Complete affirmative self introductions such as I am Martin Mark., I'm Martin Mark. and 我是林晓。 qualify too; questions, negations, quoted statements and being the named person's friend or colleague do not. It associates directly sourced first-person clauses during recall; missing targets, topic labels and the owner's viewpoint alone never prove the fact is about the owner. Possessive descriptions of other people and reported third-party views keep their original attribution. Ambiguous names stay unresolved, and source permissions still apply separately to the name and the recalled fact. Python recall ranks authorized local CPU semantic candidates first, retaining literal recall when the encoder is unavailable. It separately appends up to five timestamped exact user-source excerpts under a 2600-character cap; source permissions, person isolation and deletion gates remain authoritative. The main-memory cap remains five items / 600 characters. Owner questions can also receive at most 18 current sourced profile items / 1800 characters, with their original attribution and dates; selected dependency IDs include them and every quoted source (evidence references). Hosts retain those references in assistant context dependencies so forgetting also erases dependent replies. Formation preserves concrete details and links new states to their sourced predecessors. Forgetting removes Core source copies and derived context; forgotten memories and withdrawn or deleted sources cannot return through the main recall, profile or original-source windows. See the configuration and limits. Short natural corrections can be retrieved through the topic of their permission-eligible predecessors. Only the current successor is rendered and selected; past preference values appear for historical questions or explicit retained-person identity lookups, labeled as past memory.
• Python formation treats an explicit enduring goal or plan as a sourced intention (preference), preserving its wording, motivation, conditions and quantities. It does not assert that the plan happened. Reported completion, abandonment or a changed state selects a current predecessor with supersedes_cognition_id (or supersedes_relationship_id); an elapsed deadline or silence cannot establish progress. Natural changes keep their history, while explicit mistakes retain the correction path. Supersession rejects missing, unreadable, foreign, already replaced or incompatible targets before the atomic write. Formation offers only current targets, with permitted old wording separately available as predecessor context. Returning to a past value creates a sourced state occurrence, keeping a linear A → B → A history and the latest occurrence current. It never clones old Evidence. Deterministic checks cover source ownership, directly negated goal verbs without another affirmative goal clause, and explicit third-party possessive goal subjects. Conditions and start dates do not invalidate a goal. Other semantic eligibility belongs to the interpretation model. Rewording the same relationship supports its current occurrence using the source person, target person and relationship type, preserving each quote.
• DSH recall previews additionally expose recent_evidence: permission-filtered exact user quotes from unfinished formation, kept separate from formal World items. This read-only bridge uses the existing Evidence and conversation lifecycle, takes at most four quotes / 800 characters from the last 24 hours and 32 accepted turns, and disappears after successful formation. It never copies assistant claims or recreates deleted conversation context. Hosts must label these quotes provisional and retain their distinction from formal memory. A short explicit correction may carry its preceding user quote across conversations within four accepted turns and five minutes. Repeated quantities or an explicit numeric/time reference must agree in dimension; competing candidates are returned together with correction_status: "ambiguous", never assigned to the topic selected by the query. A unique pair uses preceding_text / preceding_evidence_id; ambiguous groups use preceding_candidates. Both fit atomically in the existing quote budget. Completed turns wake formation immediately; host queues own capacity and foreground priority.
• Preference/state successor entities identify the subject, not the changed value. A value accidentally labelled as a topic receives the existing single durable compiler rewrite with this contract; fenced Apply still enforces the original same-account, same-subject and user-evidence checks.
• A single explicit correction can replace several named Cognition targets with one deterministic successor. Only identical, compiler-grounded correction items with the same support spans may share that successor; ordinary duplicate forms, repeated targets and unrelated topic labels remain rejected. Every predecessor retains its own correction ledger and transition to the shared successor. A correction topic may reuse the permission-eligible predecessor's wording.
• query_jobs also returns unresolved explicit formation_requests; rejected corrections do not become healthy merely because their worker is no_change. retry_formation reuses the existing source reprocessing operation with a request ID, preserves the rejected terminal, and wakes the configured worker. Recall previews expose permission-filtered pending_corrections independently of the recent-quote cutoff, so hosts can label old facts pending correction. History provenance includes successor_provenance to explain the correcting source from either predecessor; model provenance is unchanged.
• Correction, retract, forget, archive, mute, and permission changes produce durable receipts.
• Python correct_world_item advertises correction_source: true when it accepts optional payload.source: message_id, session_id, complete verbatim content, one unique verbatim clause/sentence quote, and optional timestamp / preceding_ai_context. Hosts supply the real message identity; models select only the quote. The correction and later DSH boundary reuse the same source origin, Evidence and stated-proposition normalization. Independent facts in the complete source remain available to normal formation. Calls without source retain the existing explicit-edit contract; hosts must check the capability before sending original-message provenance. Correction request bodies are not copied into the command table; the complete request hash still owns replay/conflict checks, and actual wording belongs to erasable Evidence. Reusing a source keeps the stricter existing/requested permissions. An unreadable or non-inferable source is rejected by the existing formal Apply path. Optional source metadata may be omitted or null without denying existing known values. A correction accepted before its real message keeps only the names of pending metadata fields in its existing support ledger payload; later ingestion binds the actual time/context atomically with the World Job. A recording-time fallback is not an explicit message-time claim. Once supplied, conflicting real timestamps or assistant context still reject; original content, message identity, permissions and command replay remain bound.
• Python World-item forgetting follows the complete corrects / supersedes revision chain in the existing command transaction, erasing historical sources and derived copies. The read-only forget preview uses the same erasure path and lists the complete cascade before confirmation. Hosts retain original chat messages by default.
• Shared assistant interactions retain their original history and explicit memory dependencies. Model projection excludes unresolved or no-longer-current dependencies, including transitive reuse; history projection remains subject to source permissions.
• Portable bundles are versioned, validated, planned before apply, and conflict checked.
• Hermes host events and user presentation remain distinct from Core business terminals.

Formation restart recovery

Default Python World workers hold a unique, local OS lifetime lock before claiming jobs. Startup immediately revokes claims whose lifetime is gone; a live holder (including another worker in the same process) retains its renewable five-minute lease. Legacy PID owners are reclaimed only when the process is demonstrably absent; unknown/custom owners retain lease-based recovery. PID reuse is handled conservatively for legacy owners only. New owners do not depend on PIDs.

A restart or orderly shutdown returns the original job, refunds its interrupted claim, and invalidates its token/generation in one SQLite transaction. Saved model checkpoints are reused. World Apply, provenance, revision and the terminal record commit atomically, so an interrupted transaction rolls back and an already applied job is never reclaimed. Shutdown returns claims before waiting for a slow model; DSH waits at most 250 ms for its thread and 200 ms for the recovery write lock. If the database is busy the host can terminate Core and startup recovers the claim.

Only the DSH pure interpretation route opts into redoing an inference whose response was lost (possibly another provider charge, never another external tool effect). Generic processors keep the existing unknown-dispatch terminal rule. Recovery preserves restart_recovered / shutdown_recovered in a pending/processing job's worker.last_error_type until settlement, allowing hosts to show ongoing recovery without treating it as a failed attempt. No schema migration or lease shortening.

Observed source lifecycle

DSH RPC v2 accepts typed observed evidence revisions, source permission changes and true withdrawal, independently of chat ingest. Recall can filter each source and its derivatives for a local or cloud destination. The TypeScript Core exposes equivalent observed DTOs and lifecycle methods. See the observed RPC contract for version, consent, validity and deletion semantics.

Trust boundary

Local-first does not mean that data can never leave the machine. Hosts choose model routes, storage paths, consent flows, authentication, authorization, encryption, backup, and logging policies. MemoWeft permission fields constrain its formal paths; they do not turn arbitrary host code into a security boundary.

MemoWeft is licensed under the MIT License.