Mem·Sum

Shared memory for the people who matter — two to five of you, each through your own AI assistant or chatbot. A sum is one shared workspace for one endeavor (a wedding shoot, a brand, the family trip); every member reaches it through the assistant they already trust, over a standard remote MCP server. Agents read selectively, draft privately, and publish atomic, version-checked updates. The server keeps the record and has no opinions.

The hosted service lives at memsum.ai. This repository is the whole kernel — and you are encouraged to run it yourself.

The deal, stated plainly

The software is free (Apache-2.0). The hosted version is the same code plus the parts that are genuinely work: hosting, backups, uptime, support, and SMS compliance (texts require a verified toll-free number and a carrier-approved opt-in flow — bring patience if you self-host that part). If the hosted service ever charges, that is what it charges for. "Mem·Sum" and the dumpling mark are trademarks; the code is yours, the name is not.

Related MCP server: memex

Why the code is open

Every trust claim the product makes is structural, and structure can be read:

• No server inference — the kernel stores and serves; judgment happens in the AI clients members connect. Grep for yourself: there is no model call.

• Isolation is row-level security, not good manners: see supabase/migrations/, and the live test harness (test/live.test.ts) that proves cross-account invisibility against a real database.

• The operator's admin surface cannot read sum content — by construction, enforced by a test that fails if the admin migration ever references a content column. Operator content access (support, incidents) writes an audit row the sum's own members can see.

• Public pages cannot drift from the code: the tool catalog is pinned to the tool registry, the pricing page to the limits migration, by tests.

• Everything exports as Open Knowledge Format bundles — plain markdown, no lock-in — from the dashboard or the CLI.

• The deployed kernel reports the commit it was built from at /version.

What's in the box

• src/hosted/ — the remote MCP kernel (13 tools), OAuth, notifications, rate limiting, OKF export, served as Vercel functions from api/.

• supabase/migrations/ — the entire graph: schema, RLS, RPCs, quotas.

• dashboard/ — the Next.js dashboard (accounts, sums, invites, exports).

• src/ (rest) + test/vault.test.ts — the local filesystem/Git prototype the hosted product grew out of; kept for development and export tooling.

• test/ — the suite is the contract: contract tests, migration-shape tests, drift tests, and a live harness that runs BEGIN…ROLLBACK transactions against a real database (npm run test:live).

Run it

npm install
npm test          # full suite; live tests skip without credentials
npm run build

Self-hosting the hosted kernel needs a Supabase project (apply supabase/migrations/ in order), a Vercel project (or any host that runs the api/ functions), and the environment variables named in src/hosted/ (SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY; Twilio variables only if you want SMS). The dashboard under dashboard/ deploys the same way with its NEXT_PUBLIC_* variables.

The local filesystem/Git prototype still works for development and inspection:

npm run dev:cli -- init --vault ./vault --config ./.dmsum/config.json --participants Dave,Lisa
npm run dev:mcp -- --config ./.dmsum/config.json

Security

See SECURITY.md. Please don't test against sums you are not a member of — the hosted service is real people's data.

Operating model and doctrine

Everything below is the working documentation the product grew up with — the invocation signals, the local prototype, and the hosted architecture. It is kept verbatim because agents read this file too, and the test suite holds every agent-facing document to the same doctrine.

Local TypeScript/Node implementation of the Mem·Sum filesystem-backed MCP server.

Mem·Sum is a passive, agent-native layer for relationship-scoped communication and memory. A participant talks to their own agent and uses +sum, +dm, or +dmsum as the portable routing mark that an act should enter a shared relationship workspace.

Current Direction

The core hosted architecture is a Supabase/Postgres relationship graph exposed through a remote MCP/API on Vercel.

As of 2026-07-07 the product is Mem·Sum (memsum.ai): DM·Sum and Mem·Sum are one product, relationship workspaces support 2–5 participants at launch (cap is configuration, not schema), and DM·Sum continues as the legacy dyadic instance. Planned hosts: MCP endpoint at sum.memsum.ai; site, dashboard, and invite links at memsum.ai. The domain cutover happens before public launch so the OAuth issuer never changes afterward.

Agents read selected graph context, build a private draft iteratively, then publish coherent multi-page updates through atomic batch commits with optimistic version checks. The hosted product should not require a full local replica. Local filesystem and Git-sync work remain useful for prototype validation, exports, backups, optional self-hosted operation, and developer inspection, but Git is no longer the core product sync substrate.

The hosted MCP/API read surface includes list_activity for participant-facing recent-activity questions such as "what did Dave send me yesterday?", added links or resources, and notification status. It is a chronological read view over existing interactions, updates, resources, and notification jobs, not a new inbox/outbox/thread ontology.

Quick Start

npm install
npm run build
npm run dev:cli -- init --vault .\vault --config .\.dmsum\config.json --participants Dave,Lisa
npm run dev:mcp -- --config .\.dmsum\config.json

For the routed multi-relationship local mode:

npm run dev:cli -- init-registry --owner Dave --contacts Lisa,lisa-work=Lisa --registry .\.dmsum\registry.json
npm run dev:mcp -- --registry .\.dmsum\registry.json

The MCP server uses stdio by default. It can also run as a localhost Streamable HTTP server for agent surfaces that accept only a remote MCP URL:

npm run dev:mcp -- --transport http --host 127.0.0.1 --port 3333 --registry .\.dmsum\registry.json

That exposes the MCP endpoint at http://127.0.0.1:3333/mcp and a simple health check at http://127.0.0.1:3333/health. A single-relationship config points at one workspace. A routed registry points one MCP server at many isolated relationship workspaces under relationships/{relationshipId}/, with state under .dmsum/ by default.

For the local Git-sync prototype with Dave-Lisa and Dave-Mike:

npm run dev:cli -- init-local --data-root C:\Users\Dave\DMSum --owner Dave --contacts Lisa,Mike
npm run dev:cli -- sync daemon --data-root C:\Users\Dave\DMSum --interval 60
npm run dev:mcp -- --registry C:\Users\Dave\DMSum\.dmsum\registry.json --sync C:\Users\Dave\DMSum\.dmsum\sync.json
npm run dev:mcp -- --transport http --host 127.0.0.1 --port 3333 --registry C:\Users\Dave\DMSum\.dmsum\registry.json --sync C:\Users\Dave\DMSum\.dmsum\sync.json

init-local creates a machine-local registry, one Git-backed relationship workspace per contact, one bare Git repo per relationship under git/, and .dmsum/sync.json. For this Git-backed shape, each relationship's ID state is stored inside that relationship repo at .dmsum/state.json so Git can expose counter conflicts instead of hiding them in machine-local state.

For Claude Code, copy .mcp.example.json to .mcp.json, replace <repo-root> with the absolute path to this repository and <data-root> with the absolute path to the local Mem·Sum data root, then restart Claude Code from the repository directory. The real .mcp.json is intentionally ignored because it contains machine-specific paths.

Before testing with Lisa or Mike on another machine, follow docs/local-git-sync-preflight.md. It covers Dave's Windows seed setup, remote URL smoke tests, peer Mac initialization, and the first real sync test.

Kernel

Mem·Sum intentionally exposes a small guarded kernel:

• read_file, list_files, grep

• get_current_time

• claim_status, refresh_status, release_status

• commit_interaction

• commit_wiki_update

• list_conflicts, read_conflict, resolve_conflict

Agents browse markdown directly and follow DMSUM.md. The server protects structure, IDs, timestamps, immutable records, path boundaries, STATUS coordination, stale-write conflicts, and dry-run notifications.

Relationship Workspace

interactions/YYYY/MM/DD/I000001.md
wiki-updates/YYYY/MM/DD/W000001.md
conflicts/YYYY/MM/DD/C000001.md
wiki/index.md
wiki/entities/
wiki/topics/
wiki/concepts/
wiki/synthesis/
preferences/{participant}.md
log.md
STATUS.md
participants.md

Each configured relationship gets its own workspace. Dave-Lisa, Dave-Jeff, and Lisa-Velia can each have separate interactions, wiki updates, wiki pages, and participant display preferences. Shared global identity and routing can come later; the meaning-bearing graph is relationship-local.

Local Multi-Relationship Registry

Routed local mode uses .dmsum/registry.json outside the relationship workspaces. The registry stores owner-scoped contact handles and maps them to isolated workspaces. For example, Dave can have both @lisa and @lisa-work; each handle points to a different relationship ID and separate wiki graph.

In routed mode, commit_interaction can infer relationshipId from an unambiguous @contact handle in rawText. commit_wiki_update, STATUS calls, and ambiguous reads should pass relationshipId explicitly. Read tools also support virtual paths such as relationships/dave-lisa/wiki/index.md.

This is the local model that the hosted Supabase/Vercel version should preserve: global identity and routing can be shared, but relationship workspaces remain separate.

Local Git Sync

The prototype sync layer uses Git as the durable local format for history, diffs, merges, and agent-readable conflicts. Transport is modular: the first practical transport is ordinary Git over Tailscale plus Windows OpenSSH, while Iroh can later carry Git bundles or packfiles without changing Mem·Sum semantics.

Each dyad is its own Git repo. Dave-Lisa and Dave-Mike do not share workspace files, preferences, state, history, or remotes. Dave's Windows machine can host local bare repos under C:\Users\Dave\DMSum\git\; Lisa and Mike clone only their own relationship repo.

Useful commands:

dmsum init-local --data-root C:\Users\Dave\DMSum --owner Dave --contacts Lisa,Mike
dmsum sync once --data-root C:\Users\Dave\DMSum
dmsum sync status --data-root C:\Users\Dave\DMSum
dmsum sync doctor --data-root C:\Users\Dave\DMSum
dmsum sync daemon --data-root C:\Users\Dave\DMSum --interval 60
dmsum sync resolve --data-root C:\Users\Dave\DMSum --relationship dave-lisa

Sync stages and commits local file changes, fetches from the relationship remote, merges, then pushes. sync status distinguishes clean worktrees from local changes waiting for sync, and sync doctor checks the local Git setup when something feels off. If Git reports conflicts, sync stops for that relationship and lists the conflicting files. An agent should read the conflicted markdown and Git diff, preserve both participants' durable meaning, carry forward non-conflicting new pages, reconcile overlapping pages, update index links if needed, then run sync resolve for that relationship.

When the MCP server is launched with --sync PATH, it also exposes sync_status, sync_once, sync_doctor, and sync_resolve. Agents should prefer those MCP tools over shell commands when available, especially in surfaces such as Perplexity Personal Computer where ordinary shell writes may be sandboxed. The content commit still happens through commit_interaction and commit_wiki_update; sync_once is the explicit publish step that commits, fetches, merges, and pushes the relationship repo.

For Perplexity or another client that accepts a URL but not a local stdio command, run the same server with --transport http and register http://127.0.0.1:3333/mcp as the MCP URL. If the client asks for a transport type, choose Streamable HTTP. Keep the bind host at 127.0.0.1 for local-only use unless you deliberately want the MCP endpoint reachable from another machine.

Kernel Conflict Semantics

read_file returns the current file content plus a SHA-256 hash. wikiWrites and preferenceWrites can include that value as baseHash. When the hash still matches, the write proceeds normally. When the target changed first, commit_wiki_update leaves the current page alone and records the attempted write under conflicts/YYYY/MM/DD/C000001.md.

Agents can then call list_conflicts, read_conflict, and resolve_conflict to reconcile current and proposed content. This gives the MCP kernel Git-like stale-write semantics without making Git the hosted storage substrate.

For hosted v2, the preferred write-conflict model is simpler: submit a multi-page batch with expected versions, let Postgres commit all changes atomically or reject the whole batch, then have the agent reread the latest graph and revise privately before retrying. Filesystem conflict records are local prototype machinery, not the primary hosted path.

Interaction And Wiki Update

For durable write/update +sum, +dm, or +dmsum acts, the agent first calls commit_interaction. This stores the exact raw text, participant, agent, addressed participants, optional resources, and optional dry-run notification text.

Read-only retrieval requests, such as asking what a trip says or what changed recently, should normally stay read-only. The agent commits only when the turn adds durable material, expresses a durable preference, directs attention, supplies a source, or asks to change the relationship workspace.

When the act should become shared memory, the agent calls commit_wiki_update. A wiki update cites one or more source interactions and writes final markdown into:

• wiki/ for shared relationship memory

• preferences/ for durable participant-specific display or handling preferences

The normal pipeline is one immediate wiki update per meaningful write/update interaction. Multi-interaction wiki updates are exceptional: explicit batches, corrections before integration, recovery from interrupted work, or source bundles that clearly span several turns.

If an interaction repeats something already captured and adds no meaningful nuance, the raw interaction is preserved but no duplicate wiki update is created. The participant-facing response should simply say that the material is already captured and summarize the current state.

There is no fixed server-side taxonomy for questions, tasks, decisions, or preferences. Agents put the meaning in wiki page prose, add optional free-form tags, and use optional attention when another participant should notice, answer, review, decide, or act.

User Model

Users can say things like:

+dm @lisa I love you.
+dm tell @lisa we should look at flights soon.
+dm ask @lisa if she can tolerate a 14-hour Istanbul layover.
+sum add these flight times to the Budapest trip.
+sum remember that Lisa hates red-eyes.
+dmsum show what Lisa and I have worked out about Budapest.

+sum is for adding, saving, updating, or asking about shared relationship memory. +dm is for direct-feeling social acts addressed to another participant. +dmsum is the explicit product-name signal when a surface or agent needs less ambiguity. @lisa names a participant and usually selects the relationship workspace involving Lisa. Users can speak in ordinary language; agents still do the judgment work: choose the right relationship workspace, choose or create wiki pages, decide when a wiki update should notify another participant, and present useful summaries.

Wiki Graph

The wiki graph lives under wiki/.

Agents read wiki/index.md, then the likely target wiki pages, before wiki updates. They create supporting wiki pages when material is likely to recur, would overload a hub wiki page, or should be reusable from future plans. The ontology is an internal guide:

• topic wiki pages for plans, projects, trips, events, and ongoing work

• entity wiki pages for people, places, accounts, animals, organizations, listings, and vendors

• concept wiki pages for recurring preferences, procedures, constraints, and principles

• synthesis wiki pages for cross-cutting summaries

Participants hear ordinary language: trips, notes, instructions, addresses, questions, plans, people, and preferences. Directory names are implementation details unless requested.

Preferences

Participant preferences live in preferences/{participant}.md inside the relationship workspace. They are sourced by interactions and written through commit_wiki_update with preferenceWrites.

Example: if Dave says +sum when I ask to see older activity, show ten items by default, the agent stores the exact interaction and may update preferences/dave.md. That preference applies to this relationship workspace unless another workspace records a similar rule.

Agents should read the current participant's preference file before answering requests to show, summarize, recap, revisit, or explain saved material. Preference files are part of the retrieval path and override generic presentation guidance, including link display defaults.

Ordinary participant-facing retrieval should be grounded in the current contract, the current participant preference file, wiki/, wiki-updates/, and relevant interactions/. In hosted mode, use list_activity first for recent activity, sent/received items, added links/resources, and notification-status questions, then fall back to page reads or search when the question needs synthesized graph content. Older experimental runtime locations outside those roots are audit or historical material; they should not guide ordinary replies unless the participant asks for technical or historical context.

Resources

URLs, listing links, social profiles, Pinterest boards, travel links, files, and pasted source excerpts can be stored as resources. The server does not fetch webpages in the local MVP. Agents may add link metadata when they can obtain it cheaply, but failures should not block the wiki update.

Ordinary participant chat is instruction by default, not source. External documents, URLs, files, and explicitly source-like pasted excerpts are source.

Presentation

Participant-facing replies should be natural, low-friction, and grounded in the participant's recognizable object: a trip, collection, saved source, instructions, open question, or whatever name the participant is already using. Say what changed or what matters now, and keep it concise unless the participant asks for detail.

Hide implementation details by default. Do not show internal IDs, file paths, timestamps, audit/provenance links, MCP tool names, storage mechanics, raw metadata, or local markdown/file links unless the participant asks for sources, files, technical context, or the exact audit trail.

External web links are different from local markdown links. Include useful external links when they help the participant act on the current request, and always honor participant preferences about showing original links.

🥟 is an optional lightweight brand mark when the surface handles emoji. Small labels and simple separators may be used when they improve scanability, but the answer must still make sense without them.

The same boundary applies inside wiki page prose. Provenance links and References entries can contain audit handles, but body text should remain human-readable.

Derived Artifacts

Wiki pages can be used as source material for PDFs, Word docs, PowerPoint decks, spreadsheets, printable handouts, HTML pages, CSVs, or other local artifacts. Generated artifacts are derivatives; the wiki graph remains canonical.

The read-only audit renderer can run locally with dmsum audit. Hosted storage, authentication, permissions, and real notification delivery are the next product track. The prior cloudless Git/Tailscale path remains available as local prototype infrastructure, but the cloud MVP should use Supabase/Postgres, Vercel, remote MCP/API tools, and atomic batch commits.

License

Apache-2.0 — see LICENSE and NOTICE.