Memory Items

Memory items are the atomic unit of knowledge in codefidence. Each one captures a single piece of context about your codebase that is not obvious from reading the source code alone.

YAML Format

Memory items live inside domain note files in your .wiki/ directory. Each domain note is a YAML file with front matter containing a memory_items array:

yaml

domain: billing
description: Payment processing and subscription management
memory_items:
  - id: billing-001
    type: exception
    title: Never call processPayment twice for the same order
    body: |
      The Stripe API is not idempotent for payment intents by default.
      Always check order.status before calling processPayment().
      A duplicate call will charge the customer twice.
    confidence: confirmed
    status: active
    sources:
      - kind: file
        ref: src/billing/checkout.ts
        line: 42
      - kind: comment
        ref: src/billing/checkout.ts
        line: 38
    created: 2025-03-15
    updated: 2025-03-20

Types

Every memory item has a type that determines when and how it gets surfaced:

Type	Purpose	Priority
`exception`	Dangerous gotchas, edge cases, things that break silently. The most critical type.	Highest
`decision`	Architectural choices and their rationale. Explains why the code is shaped the way it is.	High
`business_rule`	Domain logic that is not obvious from reading the code. Business constraints and invariants.	Medium

Confidence Levels

Confidence tracks how sure you are that a memory item is accurate. Items start at lower levels and move up as they get validated:

Level	Meaning	Typical source
`confirmed`	Validated by a team member with domain knowledge	Manual review, code review
`verified`	Verified against the current code by automated check	`validate` command
`seen-in-code`	Observed pattern in the source code	Code scan, candidate generation
`inferred`	Deduced from code structure but not explicitly stated	AI analysis
`needs-validation`	Uncertain, requires human review before trusting	Auto-generated candidates

Sources

Each memory item can reference one or more sources that support it. Sources point back to the evidence:

Field	Values	Description
`kind`	`file`, `comment`, `doc`	Type of source evidence
`ref`	File path or URL	Location of the evidence
`line`	Number (optional)	Line number for file/comment sources

Status

Memory items have a lifecycle managed through their status field:

active — Currently relevant. Surfaced in context lookups and checked during diffs.
deprecated — No longer relevant but kept for history. Not surfaced in context lookups.

The Golden Rule

If the wiki contradicts the code, the code wins.

Memory items describe the system. They are not a specification that the code must follow. When you find a conflict, update or deprecate the memory item, do not change the code to match the wiki.