Imported from kl3inIT/MemoryOS (AGENTS.md). Install upstream with npx skills add kl3inIT/MemoryOS. Copyright stays with the author.

MemoryOS repository guide

The repository is the system of record. Chat, Linear, pull-request comments, and agent memory are inputs; durable project knowledge belongs in the documents below.

Read in this order

README.md — build and entry points.
ARCHITECTURE.md — current implemented structure and runtime flows.
docs/roadmap.md — delivered, active, and candidate increments.
The relevant capability spec under docs/specs/ and verification matrix under docs/tests/.
The active increment under docs/increments/active/ when changing in-flight work.
Accepted decisions under docs/decisions/ only when their rationale matters.

Operating rules

Keep this file a map, not an encyclopedia. Put each fact in one canonical document and link to it.
Before building a component, follow component and library reuse: always inspect and reuse suitable library components, hooks and behavior before writing custom equivalents.
Classify knowledge before writing: current implementation in ARCHITECTURE.md or docs/specs/; product intent in docs/vision.md; cross-cutting engineering policy in docs/conventions.md or docs/guidelines/; change-local reasoning in the active increment.
Treat core as capability implementation, not a framework-free domain layer. Capability code may use Spring, JdbcClient, transactions, or JPA when they reduce real complexity; forbid dependency inversion violations and speculative layers, not framework use.
Keep SQL, row mapping, locks, claims, and bulk persistence mechanics in concrete capability persistence repositories. Application services own authorization, validation, orchestration, and cross-repository transaction boundaries; do not add single-implementation repository interfaces. See persistence policy.
Keep core limited to implemented capabilities. Current modules are iam, objectstorage, connector, document, ingestion, retrieval, chat, mcp, and usage (AI usage and costs); IAM owns identity, Tenant membership, invitations, Users, Groups, and authorization. The shared connector Gradle integration bundle is organized by provider folders. Never predeclare empty future capability or provider packages.
Start non-trivial work with an increment directory containing design.md and plan.md. Update both as scope changes.
Preserve accepted MemoryOS contracts and scope while delivering production quality from the start. Scope control must not remove necessary hardening. Before proposing a departure, apply reference-based design and scope control and the relevant capability spec. Do not turn comparative research or speculative improvements into requirements.
Record an ADR only after the decision is accepted and implementation has started. ADRs are append-only; supersede them with a new ADR.
After verification, consolidate durable facts into architecture/spec/test/guideline documents in the same change. Keep the increment under active/ until the pull request merges; then move it to completed/ and reconcile the roadmap.
Never ship a temporary runtime mode, one-shot application profile, speculative endpoint, or unused abstraction to make an incomplete flow operable. Implement the real authorized runtime path, or keep the capability absent. See ADR 0002.
Test observable contracts at the narrowest useful boundary, then exercise the changed runtime surface. See testing guidelines.
Use the checked-in Gradle wrapper. clean check is the repository-wide gate.

Current active increments

Tasco scanned-PDF OCR owns OCR, extraction and indexing of the supplied financial reports, verified through Orca Sources; Search and Chat changes are excluded.
MEM-60 — Google Drive ingestion coordinates the still-active MEM-9/MEM-10/MEM-60/MEM-63 provider and acceptance scope. MEM-76 is Done and the implementation is merged; live-provider acceptance remains open.
MEM-58 — Frontend observability owns optional browser error monitoring and trace correlation.
MEM-26 — Chat reply stream replay in Redis owns moving the Chat reply replay buffer to Redis, the Onyx-style resume endpoint behavior and the browser recovery rule; several API replicas are excluded.
Time filters and documents without dates owns the rule that a missing source date does not remove a document from a Chat time filter, and the single retry when an inferred window returns nothing. Capturing Google Drive source dates during ingestion is follow-up work.
Chat limits belong to the person owns the move of the file-library ceiling into deployment configuration, the person's own storage page and retention window, and the tombstone that keeps a purged image or generated file explained on its answer.
MEM-141 — RAG benchmark owns the retrieval and answer benchmark under tools/rag-benchmark: a frozen corpus, seven question categories including Group authority, and the zero-regression gate.
MEM-77 — Provider/model administration retains the catalog administration UI and local OpenAI-compatible provider work. Its backend foundation is already implemented.
MEM-79 — Standalone OCR remains active through Worker integration and full indexing acceptance.
MEM-90 — Google Drive service-account credentials owns the additive service-account credential type with domain-wide delegation. The credential and Google Group membership for Auto Sync are implemented; whole-domain traversal and live Workspace acceptance remain open.
Chat Web search owns external Web search/URL reading; native provider-hosted adapters and live-provider acceptance remain open.
MEM-91 — Chat voice owns Onyx Voice parity: Tenant voice providers and /admin/voice, streaming dictation in Chat and Search, read-aloud, auto-send/auto-playback/auto-listen and user voice settings; audio is never stored.
MEM-112 — Chat MCP client ports the Onyx MCP client to Chat without reducing its behavior (transports, authentication types, discovery/DCR, admin tool enablement), adds several OAuth clients per server, and is accepted against Google Drive MCP; MemoryOS as an MCP server and write-tool approval are excluded.
Sign-out without the Keycloak logout page owns ending the Keycloak session by its sid through the admin API during application sign-out, with the provider logout page as fallback, and upstream (Tasco) logout through Keycloak back-channel logout on managed identity providers.
Source manager owns Group attachment owns the recorded Source manager, the Group-scoped detach command, administrator appointment and the unattached-Source warnings.
MEM-126 — SharePoint connector owns the SharePoint Online Source ported from the Onyx connector: Entra app credentials (client secret or certificate), site/library/folder scope, Onyx-style timestamp refresh with scheduled pruning, site pages, Auto Sync of SharePoint permissions like Google Drive (Q13) and the shadcn Sources surfaces.
MEM-66 — AI gateway and CPU vLLM research is parked: self-hosted model serving was removed on 2026-09-19 until a qualified environment exists.

Delivered increments are under completed; replaced research drafts are under superseded. The roadmap distinguishes the completed MEM-75 selected batch from the wider dependency issue, which remains open. Keep each increment's design, plan, verification evidence, and Linear scope aligned while implementation is in flight.

MemoryOS

About

MemoryOS repository guide

Read in this order

Operating rules

Current active increments

Canonical references

Use it

Manifest

Reviews