Layered memory
Five tiers, one repo, no lock-in.
Project knowledge is not one kind of thing. Atomic facts want a graph. Long-form prose wants a wiki. Design specs want a browsable system. Code wants a structural index. Forward-looking work wants a kanban. Memophant gives each its own tier — and keeps them all as plain markdown in your git repo.
Tier 1
Atomic facts you'll want to query, not re-read.
Memories are the smallest unit of knowledge — a decision, a constraint, a gotcha, a relation between two ideas. They're written in the basic-memory grammar (observations + relations) so every fact is searchable, every link is two-way, and every claim is provenanced to the commit it was written against.
---
title: Auth middleware rewrite
type: note
permalink: memophant/decisions/auth-middleware-rewrite
---
The legacy auth middleware was replaced with a session-token-free design.
## Observations
- [decision] Legal flagged the old middleware for storing session tokens in a way that doesn't meet the new compliance requirements. The rewrite removes server-side session state entirely. #compliance
- [risk] Backwards compatibility with v1 tokens is intentionally not preserved — pre-migration sessions must re-authenticate. #migration
## Relations
- supersedes [[auth-middleware-v1]]
- referenced_by [[release-2026-q3-checklist]]How to query
- MCP: search_notes, read_note, write_note, edit_note, build_context
- CLI: basic-memory tool search-notes (fallback)
- App: ⌘K search, the Memories tier in the sidebar
When to write here
Atomic, durable facts that should outlive the session. A decision you made and why. A constraint you discovered. A relationship between two parts of the system. If it would make a future-you grep, it belongs in Memories.
Tier 2
Prose that needs to flow.
The wiki is for long-form reference: architecture deep-dives, runbooks, design notes, anything that wouldn't compress into atomic observations without losing the throughline. Dashed filenames, internal links by name, a sidebar that you can group however you want.
---
title: Architecture-Overview
type: note
permalink: memophant-wiki/architecture-overview
---
# Architecture Overview
Memophant is a SwiftUI macOS app...
- See [Project Lifecycle](Project-Lifecycle) for the add-a-repo flow.
- See [Memory System](Memory-System) for the tier breakdown.
- See [Claude Integration](Claude-Integration) for how the API key flows.
---
_Last updated: 2026-06-02_How it's organized
- Filenames: dashed (Architecture-Overview.md)
- Links: [Title](Page-Name) — Memophant resolves them in-app
- Home.md is the landing page; _Sidebar.md groups the nav
- GitHub Wiki sync via scripts/publish-wiki.sh (Memophant auto-publish on the roadmap)
When to write here
Anything where the reader needs the throughline. How a subsystem fits together. The walkthrough of a complex flow. The runbook for an incident. Wiki pages are where you'd send a new collaborator; memories are what they'd grep when stuck.
No tier-specific screenshot yet — wiki UI shipped after the screenshot pass. Tracked for the next capture batch.
Tier 3
The system you check before touching UI.
A robust design tier turns 'what color should this be?' from a vibe-check into a lookup. Memophant treats design like wiki — plain markdown, browsable in-app — but reserved for tokens, component specs, principles, and HIG conventions. The same memory system that captures decisions also captures the visual language those decisions live in.
# Component — TierChip
Use TierChip to mark content that belongs to a specific memory tier.
Tier color is the **identity**; the chip is the **affordance**.
## When to use
- Filter chips in a list of mixed-tier content
- Page badges in commit history
- Inline mentions of tier paths (.memory/, wiki/, etc.)
## Spec
- Radius: pill (--radius-pill)
- Padding: 2.5/1 (sm/sm)
- Type: 12px medium, --tier-{slug}-fg
- Background: --tier-{slug}-tintWhat lives here
- Design system tokens (color, spacing, radii, motion)
- Component specs — the rules behind every UI primitive
- Principles — the philosophy under the system (calm, native, restrained)
- HIG / reference material relevant to the platform
When to write here
Before you build a new UI component, write the spec. Before you change a token, document the why. The design tier is what stops the design system from drifting from a coherent voice into a soup of one-off choices.
No tier-specific screenshot yet — the design tier renders identically to the wiki tier. Tracked for the next capture batch.
Tier 4
A queryable map of your symbols.
The code tier has two halves. Curated markdown overviews in code/ give a session orientation — module purpose, key types, public surface. An indexed SQLite map under .memophant/code/ answers structural questions in milliseconds. A bundled CLI (memophant code) is what Claude reaches for instead of grepping the whole repo.
$ memophant code find ConsolidationPlanner
Memophant/Services/Consolidation/ConsolidationPlanner.swift:14
struct ConsolidationPlanner
Memophant/Services/Consolidation/ConsolidationPlanner.swift:212
extension ConsolidationPlanner
$ memophant code refs ConsolidationPlanner
Memophant/Services/Consolidation/ConsolidationWizardModel.swift:88
let planner = ConsolidationPlanner(repoRoot: root)
Memophant/Tests/ConsolidationPlannerTests.swift:11
func test_planner_dedup() { ... }
$ memophant code status
clean · 165 files · 6810 symbols · indexed 412ms agoCLI verbs
- memophant code find <Symbol> — where is it defined?
- memophant code refs <Symbol> — what references it?
- memophant code outline <path> — symbol tree of one file
- memophant code imports <path> — who imports / what's imported
- memophant code search "<text>" — FTS over symbols + curated notes
- memophant code status — index health + drift
Why it exists
Memories and wiki capture what the code means. The code tier captures where the code is. Together they let an AI session resolve “fix the auth middleware” without re-reading every Swift file — the symbol query goes straight to the file, the memory query goes straight to the decision.
Tier 5
Forward-looking work, in your repo.
TASKS.md is a kanban in plain markdown. Three sections — Todo / Doing / Done — each a checklist. Move items between sections; Memophant renders the same file as a live board with drag-drop, status edits, and (optional) Claude-powered planning and execution per task. Your AI sessions read it; your future self reads it; git reviews it like any other file.
## Todo
- [ ] Tasks: add the ability to archive tasks (added: 2026-05-31)
- [ ] Public storefront repo + Heirloom Heartbeat Record (added: 2026-06-02)
- [ ] Automated wiki publish on commit. **Stopgap**: scripts/publish-wiki.sh
## Doing
## Done
- [x] Memory Engine Phase 5 — memophant-mcp stdio server + capture-replay loop
- [x] Sessions tier — collect Claude Code chat transcripts into the repoWhat you can do with it
- Drag to move between Todo / Doing / Done / Archived
- Plan with Claude — generates a plan stored in tasks/<id>.md
- Run with Claude — streams Claude output against the task
- Import from memory — promote a [todo] note to a real task
- Import from GitHub Issues — pull open issues into the board
When to write here
Anything forward-looking. Tasks are about what you'll do next; memory is about what you decided last. The boundary keeps memory free of stale to-dos, and keeps the board free of past decisions that don't need re-doing.
One repo. Five tiers. Every session, fully equipped.
The tiers aren't silos — they cross-link. A memory note can reference a wiki page; a wiki page can reference a code symbol; a task can link back to the decision that prompted it. Memophant keeps the wiring out of your way and lets you write in the right place.