Memory Types & Tagging

The quality of what Agent Brain surfaces depends on the quality of what you store. This guide covers:

• How to classify memories
• How to score importance
• How to scope memories to projects
• How to tag for filtering
• How to keep the store clean over time

The 7 Memory Types

Every memory has a type field. Pick the type that matches the information because it affects:

• How memories are grouped
• How they surface during recall
• How they are handled during audits

decision

Architectural or technical choices that should inform future work. Decisions are durable: they stay relevant even months later.

When to use: a technology was chosen, an approach was ruled out, a constraint was established.

Example: "Use PostgreSQL for all persistent writes. Redis is cache-only and must not be the source of truth for any user data."

Typical importance: 0.7–1.0

error

Bugs, root causes, and how they were fixed. The more specific the better — vague bug reports are useless when you're debugging a regression six months later.

When to use: a bug was found and fixed, a root cause was identified, a failure mode was discovered.

Example: "Race condition in cache invalidation fixed by adding a mutex in cache.py:142. Triggered when two writes landed within the same 50ms window."

Typical importance: 0.6–0.9

pattern

Recurring techniques or conventions that apply across the codebase. The distinction from decision is scope: decisions are one-time choices, patterns are things you do repeatedly.

When to use: a convention is established, a reusable technique is identified, a team standard emerges from practice.

Example: "Always use parameterized queries in this codebase. Never string-interpolate SQL, even in migration scripts."

Typical importance: 0.5–0.8

entity

Named things in the project — services, modules, classes, APIs, teams — and what they do. Gives agents a shared vocabulary for the codebase.

When to use: a service or module is introduced or renamed, responsibilities are clarified, ownership is established.

Example: "The UserService handles authentication, registration, and profile updates. It does not handle billing — that's BillingService."

Typical importance: 0.4–0.7

preference

Style and workflow preferences, usually specific to a person or team. These shape how agents communicate and code, not what they build.

When to use: a user expresses a consistent preference for format, verbosity, naming, tooling, or communication style.

Example: "This user prefers terse responses with no trailing summaries. Stop after the last substantive point."

Typical importance: 0.3–0.6

context

Temporary project state. Context memories describe where you are right now, not enduring facts.

When to use: a refactor is in progress, a feature is partially implemented, a sprint has a specific focus, a branch is in an intermediate state.

Example: "We are mid-refactor of the payment module, merging three legacy flows into a single CheckoutService. Expect incomplete state in billing/*.ts until PR #312 lands."

Typical importance: 0.3–0.6

Archive context memories when the state they describe no longer applies.

fact

General reference information that is true but low-signal — API limits, external service constraints, version pinning, third-party quirks.

When to use: a specific number or constraint matters but doesn't rise to a decision or pattern.

Example: "The Stripe API rate limit is 100 requests per second in live mode, 25 in test mode."

Typical importance: 0.2–0.5

Importance Scoring

The importance field is a float from 0.0 to 1.0. It feeds directly into the memory retrieval score (weighted at 25% by default). Set it deliberately — the default of 0.5 is fine for most memories, but the outliers matter.

Rule of thumb:

• If forgetting the memory would cause a future agent to make the wrong choice, score it above 0.7

Project Scoping

The project field scopes a memory to a specific codebase. Within a project, project-scoped memories rank higher than global ones for similar content.

Use a project scope when the fact is only true for one codebase, team, or deployment. A database choice, a module's responsibilities, a local convention — these belong on the project.

Omit the project scope (or use global) for cross-project conventions, user preferences, team-wide standards, and anything that should surface regardless of which repo the agent is working in. Examples: preferred response format, no-any TypeScript rule enforced everywhere, company-wide API security policy.

For global memories:

• You usually do not need to set a project value
• Omitting project stores the memory globally by default

Tagging Conventions

Tags improve precision during recall.

• Well-tagged memories work better in targeted searches
• Untagged memories rely more heavily on semantic similarity

Format: lowercase, hyphenated. react-query, not ReactQuery or react query.

Tag by domain:

Tag by signal type:

Tag by agent (when the memory is agent-specific):

claude, cursor, codex, aider — use these when a preference or behavior is specific to one agent's communication style or output format.

Multiple tags are fine.

• Tags are filters, not loose keywords
• brain_recall with tags: ["security", "database"] returns memories that match both tags
• Use tags to build precise recall queries

Memory Lifecycle

Memories are not temporary notes. Over time they accumulate, so cleanup matters as much as capture.

Archive, don't delete. When a memory is superseded — a decision was reversed, a bug was re-fixed, a context window closed — archive it with brain_forget. Archived memories remain queryable if you pass include_archived: true. Hard deletes are for duplicates and outright mistakes.

Consolidate near-duplicates. Run brain_audit periodically to surface clusters of similar memories. Merge them into a single high-quality memory rather than letting four slightly different versions of the same fact drift apart.

Archive context memories after each phase. A context memory describing an in-progress refactor should be archived when that refactor ships. Stale context is actively harmful — it misleads future agents about the current state.

Decisions are permanent unless explicitly reversed. Don't archive a decision just because the feature it relates to is old. If the decision is still in force, it should still be surfaced. Archive it only if a newer decision explicitly supersedes it, and link them.

Good vs. Weak Memory Examples

The difference between a useful memory and a useless one is specificity.

Example 1 — decisions:

Weak: "We talked about the database today."

Strong: "Decided to use PostgreSQL for all persistent writes. Redis is cache-only and must not be the source of truth for any user data. Decision made in architecture review 2024-11-08."

Example 2 — errors:

Weak: "Fixed the bug."

Strong: "Fixed NullPointerError in UserService.getById() caused by a missing null check on the optional email field. Affected users with OAuth-only sign-in who never set an email. Fix merged in PR #247. Add null checks to all optional profile fields."

Example 3 — patterns:

Weak: "Use TypeScript."

Strong: "All new modules must use strict TypeScript. No \any` types permitted. Enforced by tsconfig.json strict mode in the project root. Violations will fail CI."`

Use this test:

• Could a fresh agent, reading only this memory and the codebase, make the right choice?
• If not, add more context