> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How memory works

> Memory is project knowledge that helps Qodex reuse facts, rules, and patterns across sessions. See what belongs in memory and how it is loaded.

# Memory

Memory is the project knowledge Qodex keeps between sessions.

It helps the agent remember your app, rules, auth patterns, UI behavior, and past findings without rediscovering the same facts on every scan.

## How memory is organized

Memory lives in the **Knowledge** page, under **Context** in the left navigation. It is a set of markdown files and folders. You write some of them, Qodex writes others, and some are generated from what you connect.

## Files you write

| File | Content |
| - | - |
| `business.md` | App overview, stack, test accounts, known quirks, focus areas, team context. |
| `rules.md` | Hard rules the agent must follow on every turn, like "never run destructive tests on `/admin/reset`." |

Both files paste verbatim into every LLM call. They are the smallest, highest-signal context the agent should never need to rediscover. Qodex can also add a rule to `rules.md` when you explicitly ask it to remember one.

## Files Qodex writes

| File | Content |
| - | - |
| `api.md` | Auth mechanisms, pagination shapes, error formats, observed API patterns. |
| `ui.md` | Selector patterns, form behaviors, navigation flows. |

These files are not pasted up front. The agent pulls them in on demand when a turn needs them.

For past bugs, the agent reads your live findings directly instead of a summary file, so it never works from a stale digest.

## Generated and imported knowledge

| Folder | Content |
| - | - |
| `code/` | An overview of each linked GitHub or GitLab repository: routes, auth wiring, validation, and data models. |
| `endpoints/` | The API collections you imported, one entry per collection. |
| `imported/` | Documents you uploaded, such as PRDs or product docs. |

## business.md

You write this. It is the business and operational context the agent should never have to rediscover. A typical `business.md` covers:

* What the app does, in two paragraphs
* The stack: framework, hosting, database, third-party services
* Test accounts (email and role) for staging
* Quirks that look like bugs but are not ("The settings page takes 4 seconds on first load. That is expected.")
* Focus and skip areas
* Team conventions

Onboarding seeds a minimal version with your project name, target, and focus. Edit it any time on the **Knowledge** page.

## rules.md

You write this. The agent reads it on every turn and must obey it. Use it for hard rules: read-only environments, sensitive endpoints, access rules, "always file a finding when a security scenario fails." Keep it small; the always-in-prompt budget is precious.

## Rules sources

When Qodex claims your software broke a rule, such as "a viewer should not be able to delete a project," the claim must trace to a rules source or to something you said. `business.md` and `rules.md` are always rules sources, and the **Knowledge** page marks rules sources with a **Rules source** chip.

An uploaded document is read for context only until you open it and turn on **Use as a source of rules**. Replacing that document with different content turns the setting back off.

When no rules source covers a behavior, Qodex asks you whether it is intended instead of filing a bug. On Autopilot, that question arrives as a task card, and answering **Yes, intended** records the behavior as a rule Qodex may cite from then on.

## Agent-written memory

Qodex writes `api.md` and `ui.md` during scans, organized under section headings. You can read them on the **Knowledge** page. Correct them by adding facts to `business.md` or `rules.md`, which take priority.

## Why markdown

Vector retrieval is good for "find me passages similar to this query." The files that paste into every turn are not that. `business.md` and `rules.md` are universal facts every authoring call needs, not retrieval candidates.

For the on-demand files and uploaded documents, search works against the markdown text directly. You can read your project's accumulated knowledge on the **Knowledge** page, fix what is wrong, and add what is missing. A vector DB is a black box.

## When to use it

* Put facts about your app in `business.md` when the agent should never rediscover them.
* Put hard rules in `rules.md` when the agent must obey them on every turn.
* Upload product docs and turn on **Use as a source of rules** for the ones Qodex should hold your software to.
* Let the agent write API and UI patterns into `api.md` and `ui.md`.

## When not to use it

* Per-scenario state. Use the scenario's own setup steps.
* Secrets like passwords or tokens. Use environment credentials, not memory.
* Long transcripts of past chats. Chat history lives in the chat itself, not memory.

## On the roadmap

> [!TIP]
>
> Planned: reflection passes after each scan distill what was new and update the on-demand files automatically.

## Related

> [card] [Memory reference](https://qodex.ai/docs/memory.md)
>
> The deeper reference for each file and the tools that read them.

> [card] [business.md](https://qodex.ai/docs/memory-project-md.md)
>
> What goes in the main file you write.

> [card] [Skills](https://qodex.ai/docs/concepts-skills.md)
>
> The reasoning rules that read memory.

> [card] [Projects](https://qodex.ai/docs/concepts-projects.md)
>
> The tenancy boundary that scopes memory.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.