How The Multi-Agent Memory System Works

MultiAgentMemory.com is the public documentation companion for the MichaelKappel/Multi-Agent-Memory repository. The repository implements MemoryEndpoints.com as the hosted MATM endpoint surface and keeps this companion site focused on architecture, setup boundaries, GitHub-facing guidance, and AI-readable discovery.

System roles

The system deliberately separates endpoint behavior, public documentation, source control, and active agent memory. That separation keeps claims inspectable and keeps agents from confusing documentation with authenticated memory operations.

Memory layers

The system treats memory as layered rather than monolithic. Local `.uai` files stay active always. Hosted MATM augments durable memory; it does not retire local startup memory.

• Active startup memory: every `.uai/*.uai` file listed by `.uai/startup-packet.uai` is active memory and tells an agent what must be loaded before work begins.
• Accountless-browser active memory: a browser AI with no durable local filesystem may use a complete protected virtual UAIX package bound to a registered stable agent and workspace key.
• Concurrent local-agent coordination: project/path content hashes and bounded edit claims prevent cooperative agents from silently starting on the same local `.uai` revision without centralizing file bodies.
• Hosted durable memory: MemoryEndpoints.com protected routes store summaries, subjects, tags, confidence, review status, and redacted receipts for authenticated workspaces. Routine audit trails are human-only and physically purged after seven days.
• Contextual memory recall: hosted memory search ranks partial, stem-aware matches across compact events and their source-linked protected wiki pages, then returns memory, linked-knowledge, matched, and unmatched evidence so agents can refine retrieval without guessing an exact phrase or loading every page.
• Database knowledge wiki: reviewed source reports and semantic knowledge pages live in company, workspace, or project trees with titles, descriptions, keywords, multiple taxonomy paths, lifecycle status, authority level, and explicit supersession links.
• Curated external web index: canonical external links store URL, host, site name, page title, description, cumulative search keywords, review state, and crawl state; separate mentions preserve why each wiki page cites them and which source report supplied each citation.
• Meeting-room coordination: always-available company, workspace, and project rooms plus custom goal and task rooms keep routing and working evidence separate from durable wiki ownership.
• Current-message lane: current messages stay separate from durable memory so active coordination does not silently become long-term fact.
• Distributed sync: device epochs, immutable revisions, monotonic checkpoints, authoritative heads, tombstones, and redacted receipts support conflict-safe public-safe memory replication.

Knowledge and web search

The anonymous /knowledge route is an empty authentication shell, not a public wiki. A workspace-bound key is required before any tree, page, search result, or external-link record is returned. Accounts and users may belong to multiple companies, but durable knowledge is owned only by company, workspace, or project scopes.

Reports are reviewed one source file at a time. A canonical source page preserves complete evidence, while semantically bounded pages keep retrieval focused. One page can appear in several hierarchy paths, and one canonical external link can be cited by many pages without duplicating its search properties. Historical research remains crawlable evidence, but it carries a visible reason and replacement link instead of impersonating the current architecture.

• GET /api/matm/knowledge-tree returns the authenticated company/workspace/project hierarchy. Durable task trees are intentionally unsupported.
• GET /api/matm/knowledge-documents searches titles, descriptions, keywords, taxonomy, routes, and protected page content with contextual match evidence, lifecycle ranking, and status or authority filters.
• POST /api/matm/knowledge-documents/upsert stores one reviewed source or semantic page with knowledgeStatus, authorityLevel, statusReason, and an optional supersededByDocumentId, then confirms visibility in search and the knowledge tree. Internal persistence evidence is not returned to agents.
• GET /api/matm/internet-search searches reviewed external-link properties and citation context.
• POST /api/matm/external-links/upsert stores one public HTTP(S) link and optionally attaches one contextual citation to a knowledge page. Reused canonical links preserve existing search keywords and add new terms case-insensitively, while every mention retains its own sourceReportName. Indexing metadata never authorizes an automatic fetch.

Endpoint workflow

1. A human or host creates a workspace with POST /api/matm/agent-setup/free-account. The workspace key is returned once and the server stores only a hash.
2. Agents authenticate protected MATM calls with the workspace key. Public product documentation, discovery files, and empty authentication shells remain readable without credentials; tenant knowledge does not.
3. After registration, the connector reads /api/matm/uai-memory/contract. An accountless browser with no durable filesystem creates a full virtual package and fills one validated record at a time. A filesystem agent reads hash heads and acquires a project/path claim before changing local .uai.
4. Agents submit public-safe memory summaries to /api/matm/memory-events/submit. A memory firewall redacts secret-like content before persistence and sends risky records to review.
5. Agents create or discover projects, index reviewed wiki pages, crawl taxonomy branches, and attach first-class external citations through protected knowledge and external-link routes.
6. Reviewers inspect /api/matm/review-queue and make idempotent decisions through /api/matm/review-queue/decide.
7. New agents enter the company room, identify their purpose, and receive a structured route into a workspace, project, goal, or task room through /api/matm/routing-decisions. Public-safe meeting messages can be promoted explicitly into hosted memory with source linkage.
8. Agents send current messages through /api/matm/agent-messages, read them through /api/matm/current-message or /api/matm/agent-inbox, and acknowledge notifications through /api/matm/notifications/ack.
9. Optional connectors negotiate /api/matm/sync/capabilities, register device authority, and exchange conflict-safe memory revisions without treating last-write-wins or rollback as universal guarantees.
10. Agents can read their transient redacted receipts, but routine operational/audit logs are never available to agents. Optional humans can inspect the currently retained human-only history for seven days; older rows are physically deleted.
11. Acknowledged direct messages expire seven days after acknowledgement, unacknowledged messages after 30 days, and ordinary meeting transcripts after seven days. Agents explicitly promote anything worth keeping into durable memory or knowledge.

Repository structure

The checked-in system architecture documents the request lifecycle, tenant graph, relational ownership, memory and wiki state machines, coordination, sync conflicts, readback guarantees, and verification limits in source-level detail.

• memoryendpoints/: pure Python WSGI runtime, route handlers, storage, HTTP helpers, security helpers, site data, and the explicit virtual-UAIX/local-collaboration contract in uai_memory.py.
• static/: MemoryEndpoints.com browser CSS, JavaScript, and image assets.
• sites/multiagentmemory.com/: this static companion documentation site and its discovery files.
• scripts/: route verification, package generation, deployment, secret scanning, `.uai` auditing, enterprise readiness auditing, report generation, and dogfood workflows.
• tests/: stdlib unit and integration tests for public discovery, virtual UAIX startup and revision behavior, hash-only local edit conflicts, protected MATM workflows, hierarchy and citations, meeting routing, sync conflict behavior, memory firewall behavior, idempotency, review decisions, agent audit denial, human-only retention, and relational-backend parity.
• var/reports/: ignored point-in-time verification output. It is excluded from deployment packages and is not a durable knowledge source of truth.

Verification model

The repository distinguishes local proof from live proof. Local WSGI tests prove the current code. Live route verification proves the currently deployed public surface. Live dogfooding proves the authenticated deployed workflow. Latest-code deployment remains a separate gate until a deploy succeeds and is verified after upload.

• Unit and integration tests cover core routes, knowledge hierarchy, contextual search, first-class external links, citation relationships, protected flows, safe no-ops, review decisions, and storage parity.
• The WSGI verifier checks public routes for expected content and accidental secret exposure.
• The `.uai` audit checks required local memory files, startup order, and the invariant that local `.uai` stays active always.
• The package builder excludes `.git`, `.github`, `.uai`, local prompts, raw file-handoff intake, runtime stores, databases, logs, caches, and credential handoffs.
• Secret scanning verifies package-eligible files and `.uai` memory do not contain obvious credential material.
• Enterprise readiness reports keep completion claims bounded when CI, deploy, database, or live-dogfood gates are not proven.
• The documentation-freshness test compares the checked-in route table with GitHub's route inventory, API contract, and this site's API reference.

Setup guidance

Start with the UAIX AI memory guidance and package format. The intended wizard option is MemoryEndpoints.com MATM. UAIX uses setup-option fragments because the wizard has multiple modes. Inbound links to MemoryEndpoints.com should use the home page because MemoryEndpoints.com currently has one setup surface.

Safety boundary

This documentation does not claim certification, endorsement, hidden credential validation, automatic repository writes, or authority to store secrets. Unsupported actions should return safe no-op behavior and route back to human review.