Memories
The atomic unit of knowledge in Memax. Understand how memories are structured, classified, and stored.
A memory is the atomic unit of knowledge in Memax. It represents a single piece of information — a document, a decision, a code snippet, a URL reference, or any other content worth remembering.
Structure
Every memory has:
| Field | Description |
|---|---|
id | Unique identifier (e.g., mem_a1b2c3d4) |
title | Auto-generated or user-provided title |
content | The raw content (markdown, text, code) |
summary | AI-generated summary for quick scanning |
category | Classification (e.g., core, decisions, reference) |
tags | User or AI-assigned labels |
boundary | Access level: private, team, or public |
state | Processing state: active, archived, processing |
source | Where it came from: cli, web, mcp, sync, hook |
source_agent | Which agent pushed it (e.g., claude-code, cursor) |
Categories
Memax automatically classifies memories into categories. You can override these during push.
| Category | Description | Examples |
|---|---|---|
core | Architecture, design, system fundamentals | System design docs, API specs |
decisions | ADRs, trade-off discussions, why-we-chose-X | Architecture Decision Records |
reference | Runbooks, how-tos, quick-reference material | Deploy guides, API cheatsheets |
process | Workflows, procedures, standard operations | CI/CD pipeline docs, review process |
daily | Ephemeral notes, standups, daily context | Debug sessions, status updates |
research | Investigation results, benchmarks, analysis | Performance reports, tool evaluations |
Content types
Memax accepts many content types:
- Markdown — docs, READMEs, specs (
.md,.mdx) - Code files — any language, with syntax-aware chunking
- Plain text — notes, chat logs, meeting transcripts
- URLs — fetched, summarized, and stored as link references
- PDFs and images — extracted text, stored with original file reference
Deduplication
Memax deduplicates by content hash. Pushing the same content twice is a no-op — the operation is idempotent. If content changes, a new version is created.
# First push — creates the memory
memax push -f ./ARCHITECTURE.md
# ✓ Saved — "Architecture Overview" (core · private) [48ms]
# Same content — deduplicated
memax push -f ./ARCHITECTURE.md
# ✓ Already exists — "Architecture Overview" (no change)
# Modified content — new version
echo "## Updated section" >> ./ARCHITECTURE.md
memax push -f ./ARCHITECTURE.md
# ✓ Updated — "Architecture Overview" v2 (core · private) [51ms]Chunking
Large documents are automatically split into semantically coherent chunks for retrieval. The chunking strategy considers:
- Heading structure — splits at
##and###boundaries - Code blocks — kept intact, never split mid-block
- Paragraph coherence — avoids splitting mid-thought
- Size targets — chunks aim for 512–1024 tokens
Each chunk is independently embedded as a vector, so retrieval can return the most relevant section of a large document rather than the entire thing.
Chunking happens automatically during the background processing pipeline. You never need to chunk content manually.
Lifecycle
Push → Processing → Active → (Archived)- Push — content arrives via CLI, web, MCP, or sync
- Processing — classification, chunking, embedding (async, typically <5s)
- Active — ready for retrieval
- Archived — soft-deleted, excluded from recall but recoverable