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 a