Knowledge Base

The knowledge base is a folder of Markdown files with a predictable layout, so the agent always knows where to look for a piece of knowledge and where to put a new one. This page explains the layout, what belongs in each place, and what never goes in.

The layout

KB_ROOT/
  MEM.md                 the specification itself: how the agent works with all of this
  MEM.config.md          your settings (optional; defaults apply without it)
  MEM.index.md           the table of contents
  MEM.project.md         what the project is
  MEM.remote-cache.md    technical cache, only with a remote MEM source
  architecture/          how the system works today
  docs/                  feature docs, onboarding, local setup, release process
  conventions/           your project's rules: style, naming, testing, git, errors, security
  decisions/             Architecture Decision Records (ADRs)
  logs/                  one file per day: YYYY-MM-DD.md
  drafts/                work in progress, to be consolidated
  tasks/                 index.md, current/, done/
  troubleshooting/       index.md, current/, done/
  references/            links, commands, dependencies, environment variable names
  glossary/              domain terms and acronyms
  changelog/             internal technical changes: breaking, DB, API
  archive/               superseded knowledge, kept out of the working path
  extensions/            EXT.md and one folder per extension

Only the files the first session creates exist at the start (see Getting Started). Folders appear when there is something to put in them, and you can add folders of your own when useful.

What goes where

Information	Destination
How a part of the system works now (not how it ideally should)	architecture/
A feature explained, onboarding, local setup, release steps	docs/
A rule the project actually follows (required, preferred, to avoid)	conventions/
A meaningful decision and its reasons	decisions/
An investigation or plan still in progress	drafts/
A bug, an error, a recurring problem and its fix	troubleshooting/current/
A work item	tasks/current/
What happened today	logs/YYYY-MM-DD.md
A domain term	glossary/
A breaking, database or API change	changelog/
A useful link, command, or environment variable name	references/

MEM.index.md lists the important pages by category with a one-line description each. It is the first page the agent reads after the configuration, so it is updated whenever pages are added, renamed, removed or substantially changed.

Logs

A daily log records meaningful work in a few factual lines: what changed, which files, which decisions, what is pending, notes for the next session. It is not a transcript and never contains the agent's reasoning.

# 2026-04-30

## Work completed

- Reviewed authentication flow and confirmed token validation path.
- Updated `architecture/authentication.md` with the current request flow.

## Pending

- Add integration test for expired token handling.

When automatic updates are on, each new log starts with a one-line MEM update status (see Getting Started).

Decisions (ADRs)

Write an ADR when a decision matters beyond today: a new library or external service, a change to architecture, authentication, deployment or the data model, a project-wide convention, a significant trade-off, a deprecation, a security-relevant design. Not for minor implementation details.

• File name: decisions/YYYY-MM-DD-short-decision-title.md.
• Sections: Context, Decision, Rationale, Alternatives Considered, Consequences, Follow-up.
• When a decision is replaced, the old ADR is marked Superseded and links to the new one. It is never deleted: the reasoning behind a past choice is often exactly what someone needs later.

Tasks and troubleshooting

Both areas share one shape:

tasks/                    troubleshooting/
  index.md                  index.md
  current/                  current/
  done/                     done/

• current/ holds what is open, active, blocked or recurring; done/ holds what is closed but still worth keeping.
• Each area's index.md lists its items by status and is updated whenever an item is created, moved or renamed.
• A closed item keeps its history and gets a clear status (Completed, Resolved, Mitigated, Superseded, Duplicate, Won't fix...) and usually a date.
• A troubleshooting runbook for a recurring problem stays in current/ even after one occurrence is fixed; each resolution is added inside it with a date.

A troubleshooting note names the exact symptom, the context, the known or suspected cause, the solution, and the related files, so the next person who sees the same error finds the answer by searching for it.

The archive

archive/ is for knowledge that is obsolete or superseded and only clutters the working path, for example an old flow description replaced by a new one. It keeps the original category (docs/old-flow.md becomes archive/docs/old-flow.md) and archive/index.md records why and when. Finished tasks and resolved problems do not go to the archive: they go to their area's done/ folder.

What never goes in

• Secrets of any kind: passwords, tokens, keys, real environment variable values. Variable names are fine.
• The agent's raw reasoning, or whole conversations.
• Speculation with no future value, and failed attempts that teach nothing.
• Trivial changes such as typo fixes.
• Large dumps of source code: link to the file and the symbol instead.

Quality

Pages should be short, factual, easy to scan and tied to this project, not to generic best practice. When a page describes behavior inferred from the code, it names the files and symbols. When something is not verified, the page says so with a marker:

Unverified
Needs confirmation
Inferred from code
Confirmed by runtime test
Deprecated

MEM LINT reviews the whole knowledge base for stale claims, contradictions, orphan pages, missing links, items marked open that are done, and documentation that no longer matches the code. With ask_before_large_reorganization: true (the default) the agent asks before any broad restructuring.