9 KiB
9 KiB
Memory Control Plane
Control plane UI for the temporal semantic memory system built with Next.js, React, TypeScript, Tailwind CSS, and Cytoscape.js.
Overview
The control plane is a modern web application that provides a comprehensive UI for managing and visualizing temporal semantic memories. It acts as a proxy between the browser and the Python FastAPI dataplane, eliminating CORS issues and providing a clean separation of concerns.
Architecture
Browser ←→ Control Plane (Next.js) ←→ Dataplane (Python FastAPI)
The control plane:
- Serves the React UI to the browser
- Provides Next.js API routes (
/api/*) that proxy requests to the dataplane - Handles client-side state management and visualization
- Eliminates CORS issues by serving both UI and API from the same origin
Features
🔍 Search Debug (Most Important)
- Multi-pane search interface: Add multiple search panes for comparison
- Interactive search controls: Query, fact type, thinking budget, reranker selection, max tokens
- Phase-based visualization: Four phases of the retrieval pipeline
- 1. Retrieval: View results from each method (Semantic, BM25, Graph, Temporal) with ranks and scores
- 2. RRF Merge: See how Reciprocal Rank Fusion combines rankings from different methods
- 3. Reranking: Compare before/after reranking with rank changes highlighted (blue = improved)
- 4. Final Results: Detailed score breakdown with activation, similarity, recency, frequency ranks
- Comprehensive stats: Nodes visited, entry points, budget usage, results count, duration
- Trace visualization: See exactly how each retrieval method performs and contributes
📊 Data Visualization
- World Facts: View and explore general knowledge memories
- Agent Facts: Track agent actions and activities
- Opinions: Monitor agent beliefs and perspectives
- Documents: Manage source documents
Each fact type supports:
- Interactive graph visualization with Cytoscape.js (circle, grid, force-directed layouts)
- Searchable table view with filtering
- Real-time data loading
💭 Think Interface
- Ask questions to the AI agent
- View source facts used (world, agent, opinions)
- See newly formed opinions with confidence scores
- Configurable thinking budget
➕ Add Memory
- Submit new memories with context
- Support for event dates and document metadata
- Sync or async processing options
- Upsert capability for updates
📈 Statistics & Operations
- Real-time memory statistics (nodes, links, documents)
- Breakdown by fact type and link type
- Async operation monitoring (pending/failed)
- Auto-refresh every 5 seconds
Getting Started
Prerequisites
- Node.js 18.x or later
- A running dataplane API server (Python FastAPI)
Installation
npm install
Configuration
Configure the dataplane URL in .env (optional, defaults to http://localhost:8080):
cat > .env << 'EOF'
MEMORA_CP_DATAPLANE_API_URL=http://localhost:8080
EOF
Development
Terminal 1 - Start Dataplane:
# From project root
./scripts/start-server.sh
Terminal 2 - Start Control Plane:
cd control-plane
npm run dev
Open http://localhost:3000 in your browser.
Production Build
npm run build
npm start
Tech Stack
- Framework: Next.js 16 with App Router
- Language: TypeScript
- Styling: Tailwind CSS v4
- Visualization: Cytoscape.js
- State Management: React Context API
- API: Next.js API Routes (proxy to dataplane)
Project Structure
control-plane/
├── src/
│ ├── app/
│ │ ├── api/ # API routes (proxy to dataplane)
│ │ │ ├── agents/ # GET /api/agents
│ │ │ ├── graph/ # GET /api/graph
│ │ │ ├── list/ # GET /api/list
│ │ │ ├── search/ # POST /api/search
│ │ │ ├── think/ # POST /api/think
│ │ │ ├── memories/
│ │ │ │ ├── batch/ # POST /api/memories/batch
│ │ │ │ └── batch_async/ # POST /api/memories/batch_async
│ │ │ ├── documents/
│ │ │ │ ├── route.ts # GET /api/documents
│ │ │ │ └── [documentId]/ # GET /api/documents/:id
│ │ │ ├── stats/
│ │ │ │ └── [agentId]/ # GET /api/stats/:id
│ │ │ └── operations/
│ │ │ └── [agentId]/ # GET /api/operations/:id
│ │ ├── dashboard/
│ │ │ └── page.tsx # Main dashboard
│ │ ├── layout.tsx # Root layout
│ │ ├── page.tsx # Home (redirects to dashboard)
│ │ └── globals.css # Global styles
│ ├── components/
│ │ ├── agent-selector.tsx # Agent dropdown
│ │ ├── data-view.tsx # Graph/table visualization
│ │ ├── documents-view.tsx # Document management
│ │ ├── think-view.tsx # AI thinking interface
│ │ ├── add-memory-view.tsx # Memory submission form
│ │ └── stats-view.tsx # Statistics dashboard
│ └── lib/
│ ├── agent-context.tsx # Global agent state
│ ├── api.ts # API client
│ └── utils.ts # Utilities
├── .env # Environment config (optional)
└── package.json
API Routes
All control plane API routes proxy to the dataplane:
| Route | Method | Description |
|---|---|---|
/api/agents |
GET | List all agents |
/api/graph |
GET | Get graph data for visualization |
/api/list |
GET | List memory units with search |
/api/search |
POST | Search memories |
/api/think |
POST | Generate AI answers |
/api/memories/batch |
POST | Store memories (sync) |
/api/memories/batch_async |
POST | Store memories (async) |
/api/documents |
GET | List documents |
/api/documents/:id |
GET | Get document details |
/api/stats/:agentId |
GET | Get agent statistics |
/api/operations/:agentId |
GET | List async operations |
Usage
Using Search Debug (Primary Feature)
- Go to the Search Debug tab
- Enter a search query
- Select fact type (World, Agent, Opinion)
- Adjust thinking budget, reranker (Heuristic/Cross-Encoder), and max tokens
- Click Search to run the query
- Use the phase radio buttons to explore the retrieval pipeline:
- 1. Retrieval: Switch between Semantic/BM25/Graph/Temporal tabs to see each method's results
- 2. RRF Merge: View how rankings from different methods are combined with source ranks
- 3. Reranking: See rank changes (↑ improved, ↓ declined) with score component breakdowns
- 4. Final Results: Detailed table with all score components and individual metric ranks
- Monitor the status bar showing nodes visited, entry points, budget usage, and duration
- Add more panes with + Add Search Pane to compare different queries side-by-side
- Each pane maintains independent state for query, settings, and current phase view
Selecting an Agent
- Use the dropdown in the top navigation bar
- Select an agent to view their memories
- All views will automatically filter by the selected agent
Visualizing Memories
- Go to the Data tab
- Choose a fact type (World, Agent, Opinions, or Documents)
- Click Load to fetch data
- Toggle between Graph and Table views
- Use search to filter results
Asking Questions
- Go to the Think tab
- Enter your question
- Adjust thinking budget if needed
- Click Think to get an AI-generated answer
- View source facts and new opinions formed
Adding Memories
- Go to the Add Memory tab
- Enter memory content (required)
- Optionally add context, date, document metadata
- Choose sync or async processing
- Click Submit Memory
Monitoring Stats
- Go to the Stats & Operations tab
- View real-time statistics
- Monitor pending/failed async operations
- Stats auto-refresh every 5 seconds
Development Notes
- The control plane uses client-side rendering for interactive features
- API routes run on the server and proxy to the dataplane
- No direct browser-to-dataplane communication (no CORS issues)
- Graph visualization uses Cytoscape.js with multiple layout options
- Tailwind CSS v4 for styling (simplified configuration)
Troubleshooting
CORS Errors: The control plane should eliminate CORS issues. If you see them, ensure you're accessing the control plane at http://localhost:3000 (not the dataplane directly).
Connection Errors: Verify the dataplane is running at the URL specified in .env (default: http://localhost:8080).
Graph Not Rendering: Check browser console for errors. Ensure data is loading correctly from /api/graph.
Build Warnings: The "workspace root" warning about lockfiles is harmless and can be ignored.