Skip to main content
Normalized for Mintlify from knowledge-base/neurigraph-memory-architecture/neurigraph-build-plan.mdx.

Neurigraph Hyperthyme — 7-Day Prototype Build Plan

Author: Oxford Pierpont Purpose: Complete implementation spec for vibe-coding with Claude Code and ChatGPT Codex Timeline: 7 days Output: A working personal memory system with visual graph UI and MCP integration

What We’re Building

A persistent AI memory system with three axes:
  • X-axis (Breadth): A two-layer navigable knowledge graph. Layer 1 = broad topic nodes (e.g., “Medical”, “Sales”, “AI Projects”). Layer 2 = focused sub-topic nodes within each broad topic (e.g., under “Medical”: conditions, medications, hospitalizations, diet, exercise, metrics).
  • Y-axis (Depth): Each focused node is a gateway to a database of conversation chunks. Each chunk contains the full transcript (~50K tokens), an AI-generated summary, extracted keywords, timestamps, and links to any generated artifacts/files.
  • Z-axis (Time): Memory temperature. Recently accessed chunks are “hot” (uncompressed, cached). Older chunks go “warm” then “cold” (compressed, slower access). Accessing any node “warms” connected nodes across the graph, preemptively decompressing them.
The system is accessed two ways:
  1. Web UI — for the human to browse, search, and manage memories visually
  2. MCP Server — for any AI (Claude, ChatGPT, Gemini) to query and push memories during conversation

Architecture Overview


Tech Stack

Backend

  • Python 3.11+
  • FastAPI — REST API for the web UI
  • FastMCP — MCP server for AI integration
  • SQLite — knowledge graph (nodes, edges), metadata, access tracking, temperature states
  • ChromaDB — local vector database for semantic search over summaries
  • gzip — compression for cold storage chunks
  • An LLM API call (Claude or OpenAI) — for generating summaries and extracting keywords when saving chunks

Frontend

  • React 18+ with Next.js or Vite
  • TypeScript
  • Tailwind CSS
  • react-force-graph-2d — interactive draggable graph visualization
  • shadcn/ui — card components, search bar, buttons, tabs, layouts
  • Lucide icons

File Structure


Database Schema (SQLite)

Tables


API Endpoints (FastAPI)

Graph Management

Memory Operations

Temperature


MCP Server Tools

These are the tools exposed via FastMCP that any AI can call:

Key Implementation Details

Summary + Keyword Generation (summarizer.py)

When a conversation chunk is saved, make one LLM API call to generate:
  1. A 100-300 word summary
  2. 10-30 keywords/phrases
  3. A suggested topic classification (if broad/focused nodes don’t exist yet)

Search Cascade (search_engine.py)

The search follows this order (fast → slow, narrow → broad):
  1. Keyword match — exact match against keywords.txt in SQLite (fastest)
  2. Vector search — semantic match against summaries in ChromaDB
  3. Full-text search — search inside transcripts if top results aren’t confident enough
Each step returns scored results. Merge and rank by combined score.

Temperature Management (temperature_manager.py)

Run on a timer (every hour or on-demand):

Recall File Creation (memory_store.py)

When a chunk is saved:

Frontend Components

BroadGraph.tsx

  • Uses react-force-graph-2d
  • Fetches GET /api/graph/broad on mount
  • Each node is a circle with the topic name
  • Clicking a node navigates to FocusedGraph for that broad topic
  • Drag to rearrange, scroll to zoom

FocusedGraph.tsx

  • Same graph library
  • Fetches GET /api/graph/broad/{id}/focused
  • Shows sub-topic nodes + edges between them
  • Clicking a node navigates to MemoryFeed
  • Back button returns to BroadGraph

MemoryFeed.tsx

  • Fetches GET /api/memory/{focused_node_id}
  • Renders a scrollable list of MemoryCard components
  • Sort by: date (newest first), access count, temperature
  • Filter by: keyword, date range, source model

MemoryCard.tsx

  • Card layout with:
    • Header: date, source model badge, temperature indicator (🔴 hot / 🟡 warm / 🔵 cold)
    • Body: summary text (always visible)
    • Expandable: full transcript (lazy-loaded on click)
    • Footer: keyword pills, artifact links, access count
  • Styled with shadcn/ui Card component + Tailwind

SearchBar.tsx

  • Always visible at top of page
  • Calls GET /api/search?q={query} with debounce
  • Results appear in a dropdown showing: matching summary snippet, node path (Broad > Focused), relevance score
  • Clicking a result navigates to that chunk in context

ViewToggle.tsx

  • Toggles between: Feed (default), Table, and Tree views
  • Feed = MemoryCard list
  • Table = sortable columns (date, topic, summary, keywords, temperature)
  • Tree = file-system-like expandable tree (Broad > Focused > Chunks)

7-Day Build Schedule

Day 1 — Foundation + Data Layer

Assign to: Claude Code
  • Initialize project (Python backend, React frontend)
  • Set up SQLite database with full schema
  • Implement graph_manager.py — CRUD for broad nodes, focused nodes, edges
  • Implement models.py — Pydantic schemas for all entities
  • Write seed data script with 3-4 example broad topics and 5-6 focused nodes each
  • Verify: Can create, read, update, delete graph nodes via Python

Day 2 — Memory Storage + Recall Files

Assign to: Claude Code
  • Implement memory_store.py — create/read/delete memory chunks
  • Implement summarizer.py — LLM call to generate summary + keywords
  • Implement recall file creation (transcript.md, summary.md, keywords.txt)
  • Set up ChromaDB — embed summaries on save, query on search
  • Implement search_engine.py — keyword search + vector search + merge
  • Verify: Can save a conversation chunk, search for it, get it back

Day 3 — Temperature System + API

Assign to: Claude Code
  • Implement temperature_manager.py — cooling cycle, warming logic
  • Implement gzip compression/decompression for cold chunks
  • Implement cross-node warming (access node → warm connected nodes)
  • Build FastAPI app (main.py) — all API endpoints listed above
  • Add CORS middleware for frontend
  • Verify: API is running, all endpoints return correct data

Day 4 — MCP Server

Assign to: Claude Code
  • Implement mcp_server.py using FastMCP
  • Wire all 7 MCP tools to the backend API functions
  • Test with Claude Desktop or Claude Code: search_memory, save_conversation, get_context
  • Verify: Can have a conversation with Claude, save it via MCP, then retrieve it in a new conversation

Day 5 — Frontend: Graph Views

Assign to: Codex (or Claude Code)
  • Scaffold React app (Vite + Tailwind + shadcn/ui)
  • Build BroadGraph.tsx — force-directed graph of broad topics
  • Build FocusedGraph.tsx — drill-down graph for a selected broad topic
  • Build navigation flow: Broad → Focused → (placeholder for feed)
  • Build SearchBar.tsx — global search with results dropdown
  • Verify: Can click through the graph hierarchy, search returns results

Day 6 — Frontend: Memory Feed + Views

Assign to: Codex (or Claude Code)
  • Build MemoryFeed.tsx — scrollable card list for a focused node
  • Build MemoryCard.tsx — summary, expandable transcript, keywords, artifacts
  • Build ViewToggle.tsx — switch between Feed / Table / Tree
  • Build Table view (sortable data table with shadcn/ui)
  • Wire everything to the backend API
  • Verify: Full click-through from graph → feed → expanded memory works

Day 7 — Polish, Test, Integrate

Assign to: Both
  • End-to-end test: Save a real conversation via MCP → browse it in the web UI
  • Test the warming system: access a node, verify connected nodes warm up
  • Test cold storage: wait for cooling cycle, verify compression, verify retrieval still works
  • Fix bugs, improve styling, handle edge cases (empty states, errors)
  • Write a basic README with setup instructions
  • Verify: The whole system works for daily personal use

How to Hand This to Claude Code

Copy this prompt for each day’s work:

How to Hand This to Codex

For the frontend days (5-6), give Codex:

Success Criteria

At the end of 7 days, you should be able to:
  1. Browse your memory visually — click through the graph, see all your stored conversations organized by topic
  2. Search across everything — type a query, get ranked results from any topic
  3. Save conversations automatically — via MCP, any AI you talk to can push conversation chunks to the right node
  4. Retrieve context in new conversations — ask an AI about something you discussed weeks ago, and it finds the relevant memory
  5. See the temperature system working — recent memories are hot, old ones go cold, accessing one warms its neighbors

Future Phases (Not in This Sprint)

  • Cross-model live conversation sharing
  • Mobile app (React Native)
  • Defining Memories (milestone/decision detection)
  • Multi-user support
  • End-to-end encryption
  • aiConnected OS persona integration
  • Sending specific memories to conversations from the web UI
  • File tree and 2D scrollable alternative views