memoweft

MemoWeft

Long-term memory that keeps evidence, inference, and conflict distinct.

Portable, traceable user memory for TypeScript AI applications. MemoWeft keeps source records separate from model inference, preserves contradictions, and exports versioned memory bundles that hosts can validate and import.

Demo · Install · Integrations · Reference host · Docs

English · 简体中文

MemoWeft is a library your application imports — not a hosted service, chat UI, persona, vector database, or agent framework.

See the difference in 30 seconds

With Node 24 installed:

git clone https://github.com/memoweft/memoweft.git
cd memoweft
npm ci
npm run build
node examples/no-key-demo.ts

The demo uses an in-memory database and a deterministic stub model. After dependencies are installed, it needs no API key, makes no network calls, and writes nothing to disk.

[limited   ] conf  600/1000  The user lives in Osaka  — stated memory
[conflicted] conf  600/1000  The user lives in Tokyo  — conflict kept, not overwritten
[candidate ] conf  200/1000  The user probably works somewhere central  — guess (low confidence)

Summary: 3 cognitions, 1 in conflict-exposed state; inference remains labeled and rule-scored separately from stated memory.
Done. (in-memory database — nothing written to disk)

This exercises MemoWeft's public Core API and memory rules; it is not a model-quality benchmark. For correction history and typed decay as well, run npm run demo.

Read the four-scene walkthrough · Inspect the offline demo source

WeftMate in practice

WeftMate is a desktop product that uses MemoWeft to form a visible, user-editable profile from conversation threads. MemoWeft provides the portable memory layer; the product experience remains outside Core.

![WeftMate profile interface showing conversation-derived profile details that the user can review and edit]

The same behaviors are covered by offline regression cases and API-surface checks. CI runs the full guardrail suite on Node 24, Core compatibility tests on Node 22, and a built-package SQLite smoke test on Node 20. See the evaluation protocol.

Why MemoWeft

• Evidence is not belief. User statements, observations, tool results, and model inferences retain distinct provenance.
• Conflicts are exposed, not silently overwritten. Explicit corrections retain history; unresolved contradictions remain visible side by side.
• Confidence is computed by rule. The model does not directly set the numeric confidence score.
• Memory stays inspectable and portable. Cognitions trace back to evidence, and hosts can export, validate, and import versioned memory bundles.
• Assistant replies do not self-corroborate. Built-in ingestion paths may use a reply to interpret the next user turn, but do not persist that reply as evidence merely because the assistant said it.
• Staleness is typed. Transient states fade faster than durable facts and explicit preferences.

The data flow stays explicit:

evidence  →  event  →  cognition  →  recall
   ↑                       │
   └────── provenance ─────┘

Explore the six memory-discipline rules · See how the architecture enforces them

Install and make the first call

Node 24+ is recommended. Node 20 and 22 use the optional better-sqlite3 driver.

npm install memoweft

# Node 20 / 22 only
npm install better-sqlite3

Save as quickstart.mjs:

import { createMemoWeftCore } from 'memoweft';

const core = createMemoWeftCore({ dbPath: ':memory:' });

await core.ingestUserMessage({
  subjectId: 'user-42',
  content: 'I only drink decaf after 3pm — caffeine wrecks my sleep.',
});

for (const evidence of core.memory.listEvidence({ subjectId: 'user-42' })) {
  console.log(evidence.sourceKind, '·', evidence.rawContent);
}

core.close();

Run it:

node quickstart.mjs

Expected output:

spoken · I only drink decaf after 3pm — caffeine wrecks my sleep.

This first call stores and reads raw evidence; it does not pretend that storage alone is a user profile. Turning evidence into cognitions and recalled context uses a chat model. Continue with the five-minute getting-started guide.

Is MemoWeft a fit?

Choose MemoWeft when you need:

• long-term user memory across conversations, models, or hosts;
• provenance, correction history, conflict visibility, and controlled recall;
• an embedded TypeScript library backed by SQLite;
• memory that the host can inspect, manage, export, and import;
• an embedded SQLite core with explicit controls over what built-in model paths may read.

MemoWeft is not the right layer when you need:

• only short-term chat history or document RAG;
• a hosted multi-tenant memory API or managed synchronization service;
• PostgreSQL or a replaceable production storage backend out of the box;
• a ready-made persona, chat product, consent UI, or administration console.

Your host remains responsible for chat UX, consent, authentication, encryption at rest, scheduling profile updates, and deployment.

Integrations

Ecosystem	Integration surface	Availability
Vercel AI SDK	Middleware recall and controlled persistence	npm 0.2.0 supports Core 0.5.1 / 0.6
Model Context Protocol	Stdio: 5 reads and 3 controlled writes	npm 0.2.0 supports Core 0.5.1 / 0.6
Claude Agent SDK	User-prompt and tool-result hooks	Source preview
OpenAI Agents SDK	Run wrapper and model-input filter	Source preview
LangChain	v1 middleware or retriever/callback paths	Source preview
Mastra	Processor-based read/write integration	Source preview
LlamaIndex.TS	Memory block and stream tap	Legacy; upstream archived

The two published integrations — @memoweft/adapter-ai-sdk@0.2.0 and @memoweft/mcp-server@0.2.0 — install with Core 0.5.1 and 0.6. Source-preview integrations are available for evaluation from this repository and are not presented as npm-installable until released.

Run the reference host locally

The bundled host is a reference implementation, not the product. It exists so you can run Core end to end — chat with recall, visible memory formation, the evidence graph, memory management, and portable import/export — and read every call site it makes.

Requirements:

• Node 24+
• an OpenAI-compatible chat-model endpoint
• a local filesystem location for SQLite data

git clone https://github.com/memoweft/memoweft.git
cd memoweft
npm ci
npm run build
npm start -w @memoweft/host

Open http://localhost:7788.

On first run, the setup wizard saves model configuration to apps/memoweft-host/.env; memory is stored in apps/memoweft-host/data/host.db. Both paths are git-ignored. The current setup UI is Chinese. Restart the host after saving configuration.

The host is a reference implementation, not a production deployment template. See what it is and is not and review the deployment and privacy model before integrating MemoWeft into an application.

Trust, privacy, and evidence

• Offline regression coverage: cognitive rules are pinned in evaluation cases.
• Continuous verification: CI runs linting, type checking, tests, builds, API-surface checks, runnable documentation snippets, and Node compatibility jobs.
• Reproducible evaluation: BENCHMARKS.md documents the shipped regression fixtures, external-dataset protocols, publication standard, and current limitations.
• Explicit API stability: public surfaces are classified as stable, experimental, or internal in the Memory Surface Contract.
• Small dependency boundary: Node 24 uses built-in SQLite with no required third-party runtime dependency; Node 20 and 22 use the optional better-sqlite3 peer driver.
• Portable data: export, validation, dry-run import, and version checks are part of the public management surface.

Privacy boundary: MemoWeft stores memory in a standard, unencrypted SQLite database. Built-in write paths honor allowCloudRead when assembling cloud-model prompts; the flag is not access control, disk encryption, or a guarantee about custom integrations. Hosts own consent, role boundaries, deletion UX, access control, backups, logging policy, and OS- or host-level encryption.

Built with MemoWeft

WeftMate is a desktop companion built on MemoWeft. It shows what the library's guarantees look like once a real product surfaces them — the screenshots below are its UI, not a mockup, and every label in them maps to a Core concept.

Stated facts and model guesses are not shown as the same thing. Each memory carries its type, its confidence tier, and an expandable trail of the utterances it came from — with a permanent-delete control next to it. "The user is a backend developer" (volunteered) and "the user leans introverted" (the assistant guessed, the user said "yeah") end up in different tiers by construction.

Short replies are resolved before anything is stored. Here the assistant guesses, the user answers with two characters, and Core records what that actually asserts — without promoting the assistant's proposal into a user statement.

Every cognition stays traceable to its evidence. The graph is the evidence → event → cognition chain, navigable from the subject outward.

Memory is portable and deletable, in the user's hands. Export produces the versioned bundle described in the Memory Surface Contract; import previews counts before writing; clearing memory and deleting all local data are separate, explicitly irreversible actions.

Documentation

• Getting started — evidence to first recalled profile
• Concepts — six memory-discipline rules
• Examples — Core, management, plugins, and portable bundles
• API surface contract
• Glossary
• Reference host
• Deployment and privacy
• Full documentation index

Project status

MemoWeft is pre-1.0 and library-first. Core is implemented and tested, but experimental interfaces may change between minor releases.

Changelog · Roadmap · Contributing · Support · Security

If MemoWeft's memory model is useful to your work, consider starring the repository or sharing the offline demo with another builder.

License

MIT © 2026 MemoWeft contributors.