Memory Items (V2)
Memory items are the core knowledge unit in Contox's current (V2) system. Unlike V1 contexts which are manually created and managed, memory items are produced by AI enrichment from raw events captured during coding sessions. Each item represents a discrete piece of project knowledge with structured metadata, confidence scoring, and lifecycle tracking.
Data Model
| Field | Type | Constraints | Description |
|---|---|---|---|
itemId | string | auto-generated (ULID) | Unique identifier |
type | enum | see Item Types below | Classification of knowledge |
title | string | max 200 characters | Concise description |
facts | string | multi-line, max 5,000 characters | The core knowledge content |
rationale | string | null | max 2,000 characters | Why this decision/approach was taken |
impact | string | null | max 1,000 characters | Consequences or scope of impact |
files | string[] | max 50 entries | Related file paths |
schemaKey | string | from taxonomy | Hierarchical category (e.g., root/frontend/hooks) |
commitRange | string | null | SHA..SHA format | Git commit range that produced this item |
confidence | number | 0.0--1.0 | How confident the system is in this item's accuracy |
status | enum | see Status Lifecycle below | Current lifecycle state |
evidenceRefs | string[] | evidence IDs | References to source evidence |
dedupHint | string | null | category:topic:key format | Deduplication key for merging related items |
tags | string[] | max 5, lowercase with hyphens | Categorization tags |
importance | integer | null | 1--5 | How critical this knowledge is |
sessionId | string | required | The session that produced this item |
mergedFrom | string[] | item IDs | IDs of items that were merged into this one |
supersededBy | string | null | item ID | Points to the item that replaced this one |
lastReinforcedAt | string | null | ISO date | When overlapping evidence last confirmed this item |
Item Types
Each memory item has a type that determines how it is categorized and displayed in the brain:
Decision
Architectural or design choices that affect the project's direction. These capture the "why" behind technical decisions.
Example: "Chose Appwrite over Supabase for BaaS due to self-hosting capability and Frankfurt region availability."
Convention
Coding standards, style rules, and team agreements. Conventions help AI assistants follow established patterns in future sessions.
Example: "Void arrow functions MUST have braces: () => { setState(x); } not () => setState(x)"
BugFix
Bugs that were diagnosed or fixed, including the root cause and resolution. Items are marked with status deprecated when the bug is resolved, or active when diagnosed but not yet fixed.
Example: "Fixed CSS z-index stacking issue in modal overlay by moving portal to document body."
Todo
Pending tasks, known issues, and planned improvements. Active todos appear prominently in the brain's Layer 1.
Example: "Migrate session storage from cookie-based to server-side tokens before v2.0 launch."
ArchitectureNote
High-level architectural observations about the system's structure, patterns, or infrastructure.
Example: "Landing page split into 12 components in src/components/landing/ with barrel exports via index file."
ImplementationFact
Concrete facts about what was built or changed that would be useful for an AI assistant in a future session. These are the most common item type.
Example: "Added FlickeringGrid animated background component to hero section, using canvas-based rendering for performance."
CodeMapNode
Generated by contox scan -- represents a structural element of the codebase (route, component, hook, etc.). These are created without LLM involvement and are typically classified as Layer 3 (archive).
Example: "Route: src/app/dashboard/settings/page.tsx -- Dashboard settings page with usage stats and team management."
Confidence Scoring
Every memory item has a confidence score between 0.0 and 1.0 that reflects how reliable the extracted knowledge is:
| Range | Meaning |
|---|---|
| 0.9--1.0 | Very high confidence. Direct evidence from code, commits, or explicit statements. |
| 0.7--0.89 | High confidence. Clear evidence with minor inference. |
| 0.5--0.69 | Moderate confidence. Requires some interpretation of the evidence. |
| 0.3--0.49 | Low confidence. Significant inference from limited evidence. |
| 0.0--0.29 | Very low confidence. May be speculative or poorly supported. |
Items with confidence below 0.4 that are older than 14 days are automatically classified as Layer 3 (archive) and excluded from the brain document.
Evidence Verification
Confidence is reinforced by programmatic quote verification during enrichment. Each memory item must include evidenceSpans -- verbatim quotes from the source evidence. If none of the quoted strings can be found in the referenced evidence text, the item is rejected as hallucinated and never stored.
Importance Scale
The importance field uses a 1--5 scale with strict calibration:
| Score | Meaning | Examples |
|---|---|---|
| 5 | Project-defining. Wrong choice = major rework. | "Chose PostgreSQL over MongoDB", "Migrated REST to GraphQL" |
| 4 | Impacts multiple features or developers. | "Auth token format changed", "New API versioning scheme" |
| 3 | Useful context for future work in the same area. | "Added retry logic to webhook", "Refactored sidebar" |
| 2 | Minor implementation detail (default when uncertain). | "Increased spacing", "Renamed variable" |
| 1 | Trivial change unlikely to matter again. | "Fixed typo in comment", "Updated copyright year" |
For bug fixes, importance reflects the impact of the bug, not the effort to fix it. A CSS spacing fix scores 1--2; a data loss bug scores 4--5.
Status Lifecycle
Memory items progress through a defined lifecycle:
stateDiagram-v2
[*] --> active : Created by enrichment
active --> stale : No reinforcement / age decay
active --> superseded : Replaced by newer item
active --> review : Flagged for manual review
stale --> active : Re-reinforced by new evidence
stale --> archived : Confirmed outdated
stale --> superseded : Replaced
superseded --> archived : Cleanup
review --> active : Approved
review --> archived : Rejected
| Status | Description | Brain Inclusion |
|---|---|---|
active | Current, valid knowledge | Included (Layer 1 or 2) |
stale | Not reinforced recently, may be outdated | Included at reduced priority |
review | Flagged for human review (e.g., contradiction detected) | Excluded |
superseded | Replaced by a newer item (linked via supersededBy) | Excluded (Layer 3) |
archived | Confirmed outdated or no longer relevant | Excluded (Layer 3) |
Deduplication
The dedupHint field prevents duplicate items from accumulating in the brain. It uses a three-segment format:
category:topic:key
For example: bugfix:auth:token-refresh, decision:database:chose-appwrite, implementation:sidebar:refactor-v2.
During enrichment, items sharing the same dedupHint prefix (first two segments) are consolidated. Only the highest-scoring item from each dedup group is included in the brain. When enriching new events, the existing brain's dedup hints are fed to the LLM so it can reuse hints for overlapping topics rather than creating duplicates.
Managing Memory Items in the Dashboard
You can browse, review, and manage all memory items from the Memory page in the Brain tab:
- Browse -- The brain tree shows all items organized by schema key hierarchy. Expand nodes to explore
- Filter -- Filter items by type, status (draft/approved/deprecated), confidence, and schema key
- Review -- Click any item to see its full content, evidence spans, related files, and metadata
- Approve/Deprecate -- Approve high-confidence items to include them in the brain, or deprecate outdated ones to exclude them
- Edit -- Modify an item's title, content, type, or schema key to correct AI-generated content
- Bulk actions -- Select multiple items to approve, deprecate, or delete in batch
The Search tab provides semantic search across all memory items, returning confidence-ranked results relevant to your query.
Use the Hygiene tab to run the automated cleanup agent. It detects duplicates, outdated items, and quality issues, then proposes safe edits for your approval.