-
Notifications
You must be signed in to change notification settings - Fork 3
Concepts
🌐 English · 한국어
This page explains the ideas behind MemoryWeft (MWeft) — what it stores, how it is structured, and why it is shaped the way it is. For installation see install.md; for how an AI uses the tools see prompt_guide.md.
MWeft is a long‑term memory for AI that runs locally. Where most memory systems treat stored text as a flat pile (RAG) or as a knowledge graph to be analysed (GraphRAG), MWeft sits in between: it keeps both the content of what happened and the structure of how things connect, and it is built around comparison — finding what is similar to, related to, or different from something else.
Two properties make it distinct:
- Memory you can prepare in advance. You can seed memory before any conversation — a project's documents, the cast of a novel, a body of reference knowledge — so the AI already has context to build on.
- Local‑first. Everything lives in a database on your machine (SQLite) or a database you control (PostgreSQL). No data has to leave your environment, which makes a private, organization‑specific AI assistant practical.
A traditional graph connects nodes with relations. MWeft inverts the emphasis. The unit that carries meaning is the event, and an event behaves like an edge that binds together the objects that appear in it.
- Entity — an object that appears in your data: a person, a file, a place, a concept.
- Event — a document or a conversation turn, analysed as a thing that happened in which several entities took part. The event is the record; it also acts as the edge linking those entities.
From entities and events, two complementary graphs emerge:
- Entity ↔ entity graph — entities linked through the events they share. Answers “who was involved with whom, in what, and how.”
- Event ↔ event graph — events linked through the entities they share. Answers “how do separate moments connect through common participants.”
Both entities and events carry an embedding vector. That means search is not only keyword matching — you can find events with a similar context and entities that are semantically close, and you can surface relationships that plain text search would miss. Because retrieval is comparison‑based, it can return things that are alike and things that are pointedly different but related.
Memory is organised at three levels, which you can mix:
- Separate databases — keep a distinct database per project, organization, or personal use.
- Domains — partition a single database into domains so unrelated content (e.g. work vs. personal) never bleeds together.
- Groups / Tags — within one database, label content by topic. Tags are cross‑cutting (a tag name is unique and can apply across domains) and can be hierarchical (a tag may have a parent tag).
Some labels cannot be extracted from content alone — a project name or an author, for example. These you predefine as tags so they are stored alongside the events they belong to. The AI may also attach suitable tags automatically when saving.
Beyond the tags you define, MWeft can discover topic clusters automatically by community detection over the graph. These auto‑tags give you a map of the whole memory — its major themes, their sizes, and representative members — which you can ask the AI to summarize (“summarize the clusters”).
An entity never attaches directly to a tag or group. Its membership is
always derived through the events it participates in
(entity → event → tag). This keeps the structure honest: an entity belongs to
a topic only because of something that actually happened, not because of a
hand‑drawn link. It also means deleting or merging entities changes the graph,
so do it deliberately (prefer merge over delete for duplicates).
- Code / project memory — relate documents, code, and version‑control history so the AI can answer questions about the project as a whole, and compare a change against similar past changes.
- AI memory — record conversations between you and the AI (and between AIs). Most valuable for shared, multi‑person work where context accumulates.
- Narrative — track the characters and events of a novel or game, then check a new scene for consistency against what came before.
- Reference knowledge — structure large bodies of law, medicine, or history for precise similar‑case retrieval.
- MWeft leans on the underlying LLM, so summaries can contain inaccuracies; treat an event's stored summary as an LLM‑written gloss, not verbatim source.
- A memory store can accumulate both junk and signal; predefining tags and pruning helps keep retrieval focused.
- For a single user, SQLite is plenty. Concurrent multi‑user writes require PostgreSQL — see Data model.
- Data model — the objects and relationships in detail
- install.md — installation and embedding options
- prompt_guide.md — how an AI searches and saves