{ "markdown": "
\n\n\n \n \n \"MemoWeft\n\n\n# MemoWeft\n\n### Give your AI a memory—without turning its guesses into your facts.\n\nMemoWeft is an open-source long-term memory engine for TypeScript AI applications. It keeps what users said, what systems observed, what models inferred, and what remains conflicted as distinct records—so memory can be inspected, corrected, managed, and moved between hosts in SQLite controlled by your application.\n\n[![npm stable](https://img.shields.io/npm/v/memoweft?style=flat-square&label=stable&labelColor=14110B&color=E2A75E)](https://www.npmjs.com/package/memoweft)\n[![CI](https://img.shields.io/github/actions/workflow/status/memoweft/memoweft/ci.yml?style=flat-square&labelColor=14110B&label=CI)](https://github.com/memoweft/memoweft/actions/workflows/ci.yml)\n[![Node](https://img.shields.io/badge/Node-20%20%7C%2022%20%7C%2024-4A4438?style=flat-square&labelColor=14110B)](./docs/INSTALL.md)\n[![license](https://img.shields.io/badge/license-MIT-4A4438?style=flat-square&labelColor=14110B)](./LICENSE)\n\n[Why](#why-ai-memory-needs-a-paper-trail) · [Offline demo](#try-it-without-an-api-key) · [Quickstart](#quickstart) · [Integrations](#integrations) · [Trust](#trust-privacy-and-local-boundaries) · [Docs](#documentation-and-community)\n\n**English** · [简体中文](./README.zh-CN.md)\n\n
\n\n> [!IMPORTANT]\n> MemoWeft is a library your application imports—not a chat product, hosted memory service, persona framework, vector database, or agent framework.\n\n## Why AI memory needs a paper trail\n\nAI can already hold a convincing conversation. What it often lacks is reliable continuity.\n\nAcross conversations, important context can disappear. New information may quietly replace old information. A model's guess may return later as if the user had stated it. Move to another model or host, and the accumulated memory may be left behind.\n\nMemoWeft does not ask a model to declare the truth. It preserves where information came from, when it appeared, what contradicts it, and why a memory was formed—so applications and users can inspect the path from evidence to recall.\n\n\n \n \n \n \n \n
\n Evidence stays evidence

\n User statements, observations, tool results, and model inferences keep distinct provenance.\n 		\n Conflict stays visible

\n Corrections retain history. Unresolved contradictions are exposed instead of silently overwritten.\n 		\n Memory stays yours

\n Hosts can inspect, manage, export, validate, and import versioned memory bundles.\n
\n\nConfidence is computed by rule rather than copied from a model's self-assessment. Transient states can age faster than durable facts and preferences. Built-in ingestion paths do not turn an assistant's own reply into user evidence simply because the assistant said it.\n\n[Explore the six memory-discipline rules](./docs/concepts/README.md) · [Read the architecture](./docs/internals/architecture.md)\n\n## Try it without an API key\n\nWith Node 24 installed:\n\n```bash\ngit clone https://github.com/memoweft/memoweft.git\ncd memoweft\nnpm ci\nnpm run build\nnode examples/no-key-demo.ts\n```\n\nAfter dependencies are installed, this deterministic demo needs no API key, makes no network calls, uses an in-memory database, and writes nothing to disk.\n\n```text\n[limited ] conf 600/1000 The user lives in Osaka — stated memory\n[conflicted] conf 480/1000 The user lives in Tokyo — conflict kept, not overwritten\n[candidate ] conf 200/1000 The user probably works somewhere central — guess (low confidence)\n\nSummary: 3 cognitions, 1 in conflict-exposed state; inference remains labeled and rule-scored separately from stated memory.\nDone. (in-memory database — nothing written to disk)\n```\n\nThis proves MemoWeft's memory rules; it is not a model-quality benchmark. For correction history and typed decay as well, run `npm run demo`.\n\n[Read the four-scene walkthrough](./docs/demo-script.md) · [Inspect the demo source](./examples/no-key-demo.ts)\n\n## What it looks like in a product\n\n[WeftMate](https://www.weftmate.com/) is a desktop product built on MemoWeft. It turns the Core memory model into a visible profile, source trail, conflict view, and user-facing controls.\n\nThe screenshots below show **WeftMate's UI**, not UI bundled with MemoWeft Core. MemoWeft provides the memory layer and portable data contract; product experience remains the host application's responsibility.\n\n\n \n \n \n \n \n \n \n \n
\n \"WeftMate\n \n \"WeftMate\n
Know what a memory came from. Each item can expose its type, confidence tier, and source trail.Resolve short replies before storing them. A brief confirmation does not promote the assistant's proposal into user evidence.
\n\n[See the evidence graph](./assets/weftmate-memory-graph.png) · [See portable-data controls](./assets/weftmate-data-portability.png) · [Run the reference host](./docs/reference-host.md)\n\n## Quickstart\n\nNode 24+ is the simplest path:\n\n```bash\nnpm install memoweft\n```\n\nOn Node 20 or 22, also install the optional SQLite driver:\n\n```bash\nnpm install better-sqlite3\n```\n\nSave as `quickstart.mjs`:\n\n```js\nimport { createMemoWeftCore } from 'memoweft';\n\nconst core = createMemoWeftCore({ dbPath: ':memory:' });\n\nawait core.ingestUserMessage({\n subjectId: 'alice',\n content: 'I only drink decaf after 3pm—caffeine wrecks my sleep.',\n});\n\nfor (const item of core.memory.listEvidence({ subjectId: 'alice' })) {\n console.log(item.sourceKind, '·', item.rawContent);\n}\n\ncore.close();\n```\n\nRun it:\n\n```bash\nnode quickstart.mjs\n```\n\nStoring and reading raw evidence needs no model or network. Turning evidence into a profile, separating guesses from stated facts, and recalling it into later conversations requires a chat model. Embeddings are optional; without them, Core normally uses local FTS5 keyword recall.\n\n[Continue with the five-minute guide](./docs/getting-started.md)\n\n## How it works\n\nMemoWeft keeps the journey from source material to recalled context explicit:\n\n```text\nuser words · observations · tool results\n │\n ▼\n evidence\n │ provenance retained\n ▼\n event\n │\n ▼\n cognition ◀── corrections and conflicts\n │\n ▼\n recall\n```\n\nThe supported application path is the `createMemoWeftCore()` facade. Lower-level exports exist for advanced composition and carry documented stable, experimental, or internal support tiers.\n\n[API surface and tiers](./docs/reference/api-surface.md) · [Memory surface contract](./docs/reference/memory-surface-contract.md)\n\n## Is MemoWeft a fit?\n\n| Choose MemoWeft when you need… | Choose another layer when you need… |\n| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |\n| Long-term user memory across conversations, models, or hosts | Only short-term chat history or general document RAG |\n| Provenance, correction history, conflict visibility, and controlled recall | A ready-made chat UI, persona, or consumer application |\n| An embedded TypeScript library backed by SQLite | A hosted multi-tenant memory API or managed synchronization service |\n| Memory the host can inspect, manage, export, and import | PostgreSQL or a replaceable production storage backend out of the box |\n| Explicit controls over built-in model read paths | A library that supplies authentication, consent UI, compliance, or encryption at rest |\n\nYour host remains responsible for product UX, authentication, authorization, consent, encryption, backups, logging policy, and deployment.\n\n## Integrations\n\n| Ecosystem | Integration surface | Current public status |\n| ------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------ |\n| [Vercel AI SDK](./packages/adapter-ai-sdk) | Middleware recall and controlled persistence | npm `0.2.3` supports Core `0.5.1` through stable `1.x` |\n| [Model Context Protocol](./packages/mcp-server) | Stdio: five reads and three controlled writes | npm `0.2.3` supports Core `0.5.1` through stable `1.x` |\n| [Claude Agent SDK](./packages/adapter-claude-agent-sdk) | User-prompt and tool-result hooks | Source preview |\n| [OpenAI Agents SDK](./packages/adapter-openai-agents) | `run()` wrapper and model-input filter | Source preview |\n| [LangChain](./packages/adapter-langchain) | v1 middleware, retriever, and callback paths | Source preview |\n| [Mastra](./packages/adapter-mastra) | Processor-based read/write integration | Source preview |\n| [LlamaIndex.TS](./packages/adapter-llamaindex) | Memory block and stream tap | Legacy; upstream archived |\n\nPublished packages and repository source move on independent release schedules. Check the installed release's npm metadata and package README for its exact compatibility range. Source previews are not presented as npm-installable until released.\n\n[Vercel AI SDK recipe](./docs/recipes/vercel-ai-sdk.md) · [MCP recipe](./docs/recipes/mcp-server.md) · [Integration guide](./docs/integration.md)\n\n## Trust, privacy, and local boundaries\n\nMemoWeft is local-first through inspectable boundaries—not through a promise that data can never leave the device.\n\n- Memory is stored in an application-selected SQLite database; no managed memory service is required.\n- Raw evidence can be stored and read fully offline, and the repository includes a deterministic no-key demo.\n- Profile formation needs a chat model. Hosts may use a cloud or local OpenAI-compatible endpoint.\n- `allowCloudRead` filters evidence for MemoWeft's built-in cloud write-model prompts. It is not access control and does not govern custom code, recall, MCP tools, adapters, exports, or logs.\n- Observations and tool results default to ineligible for built-in cloud write prompts, but the host still owns consent, review, and authorization-change flows.\n- MemoWeft does not encrypt the SQLite file. Authentication, tenant isolation, encryption at rest, backups, logging, and compliance remain host responsibilities.\n- Forced removal of one evidence item removes its dependent derived events and cognitions and leaves an audit tombstone; it is not per-row physical erasure. Use `resetSubject` for a subject-level clear, and handle external indexes, logs, and backups at the host layer.\n\nCI verifies offline regressions, API snapshots, runnable documentation snippets, builds, and Node compatibility. Published evaluation results document both their methodology and what they do not measure.\n\n[Evaluation protocol](./BENCHMARKS.md) · [API stability](./docs/STABILITY.md) · [Deployment and privacy](./docs/deployment.md) · [Security policy](./.github/SECURITY.md)\n\n## Project status and roadmap\n\nMemoWeft is library-first, and Core 1.0 is the first stable release of its supported TypeScript facade and memory contract. A plain `npm install memoweft` follows the stable `latest` line.\n\nStable, experimental, and internal surfaces are documented separately. After 1.0, breaking a stable symbol requires a major release and prior deprecation; experimental interfaces may still change in a minor release with notice. The Python package remains an experimental parity implementation rather than a feature-complete stable SDK.\n\n**Now:** maintain the Core 1.x contract, expand versioned integrations, preserve Node 20/22/24 coverage, grow reproducible evaluation artifacts, and complete portable-bundle parity across TypeScript and Python.\n\n[Roadmap](./ROADMAP.md) · [Changelog](./CHANGELOG.md) · [Stability policy](./docs/STABILITY.md)\n\n## Documentation and community\n\n- [Getting started](./docs/getting-started.md) — from first evidence to recalled profile\n- [Concepts](./docs/concepts/README.md) — six memory-discipline rules\n- [Examples](./examples) — Core, management, plugins, and portable bundles\n- [Documentation index](./docs/README.md) — reference, recipes, deployment, and internals\n- [GitHub Discussions](https://github.com/memoweft/memoweft/discussions) — usage help and design conversations\n- [Issues](https://github.com/memoweft/memoweft/issues) — reproducible bugs and concrete feature requests\n- [Contributing](./CONTRIBUTING.md) — development setup and review expectations\n- [Support](./SUPPORT.md) — where to ask and what information to include\n\nContributions are welcome beyond Core code: clearer examples, framework integrations, platform testing, reproducible evaluation cases, and reviews of provenance, conflict, deletion, and privacy boundaries.\n\nIf you believe AI memory should be traceable, correctable, and portable—not an invisible black box—**star MemoWeft**, run the offline demo, or tell us what kind of memory experience you are building.\n\n## License\n\n[MIT](./LICENSE) © 2026 MemoWeft contributors.\n", "bytes": 14442, "sha": "0292ca2d79ae14f61e13e8bd549bea6feb8e4392cd4940ab4cf9eac9353e76f9", "repo_slug": "memoweft/memoweft", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_memoweft_memoweft_ae8eb4eb/readme" }