100-AGENT RECURSIVE MEMORY ENGINE

Full-Stack Swarm OS
Blueprint

A persistent, self-improving memory fabric. Frontend React lattice, FastAPI backend, 100-agent consensus engine, SQLite/Postgres vector store. Designed to become 100% like you after 1,000 interactions.

Get Starter Code
ASK → ENCODE → RETRIEVE → VOTE → ANSWER → STORE
Live Swarm Lattice (10×10)
100 RecursiveMemory instances 66/100 consensus • 4.2ms

1. Architecture Diagram

Four-tier design with persistent vector memory. Everything flows through the consensus engine.

Frontend
React / Next.js
10×10 lattice • Tool builder
API Gateway
FastAPI
/ask /learn /create /memory
100x
Swarm Engine
Python / NumPy
vote • improve • mutate
Database
SQLite / Postgres + FAISS
triples • memories • vectors
Click to animate ask → answer cycle
1 ask 2 encode 3 retrieve 4 vote 5 answer 6 store

2. The Three Layers

Separation of concerns: stateless UI, stateful gateway, emergent engine.

BACKEND • FastAPI

Endpoints
POST /askquery swarm
POST /learnteach triple
POST /createforge tool
GET /memorydump state
GET /knowledgesearch triples
SQLite Tables
knowledge_triples
memories (vector[5], text, ts)
conversations
tools
swarm_state
Vector Index

FAISS or sqlite-vec for cosine similarity over 5D memory vectors. Persists across restarts.

ENGINE • 100 Agents

class RecursiveMemory:
vector: float[5]
text: str
result: any
timestamp: int
Core Methods
store(v,t,r)
retrieve(k=6)
improve()
vote(q)
Consensus66/100

Recursion: improve() retrieves from 6 neighbors, mutates, votes again

FRONTEND • React

Three Modes
RECALL
Query memory, retrieve similar vectors
FORGE
Mutate + vote to create new tools
SOCRATIC
Swarm asks you, builds triples
Visualizations
Live 10×10 lattice • Memory graph (force-directed) • Tool builder with live preview

3. Knowledge Base Design

It doesn't just store facts. It stores you — your patterns, timing, vocabulary, and logic.

✓ How it becomes 100% like you

1
Stores triples: (subject, predicate, object)
(Socrates, taught, Plato) • (you, prefer, concise answers)
2
Stores full context with timestamps
"You told me on Tuesday at 14:22 that when you say 'hold' you mean [2,2,2]"
3
Learns your patterns
When you say "hold" → vector averages to [2,2,2]. When you type "?" → you want Socratic mode.
4
After 1,000 interactions, it mirrors your reasoning
Retrieval bias shifts to your vectors. Consensus threshold adapts to your confidence patterns.

Live Triple Store

001youpreferconcise answers
002holdmeans[2,2,2]
003SocratestaughtPlato
004yousaid on Tuesday"use 66% threshold"
vectors indexed • cosine similarity active 4 triples

4. The Conversational Loop

Not ingestion. Dialogue. The swarm switches sides when confidence drops.

ASK ANSWER LISTEN ANSWER ASK REPEAT SWITCH SIDES
Normal Mode

You ask → swarm retrieves 6 neighbors, votes (66/100), answers, stores interaction.

Socratic Mode

Swarm asks you → confidence < 0.4 or command /socratic → you teach → triple stored.

Confidence 0.72

Triggers switch when < 0.4

5. Code Starter Kit

Copy-paste complete. Run with docker-compose up. Built for persistence, recall, and self-improvement.

Quick Start
git clone <repo>
cd swarm-os
docker-compose up --build
Test It
curl -X POST localhost:8000/ask \
-d '{"q":"what is hold?"}'
Persist
SQLite at ./data/swarm.db survives restarts. Mount volume in compose.

Swarm OS console

Lattice 10×10
Memory

        

      

    

  





`,
            compose: `# docker-compose.yml
version: "3.9"
services:
  api:
    build: ./backend
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
      - ./engine:/app/engine
      - ./database:/app/database
    environment:
      - PYTHONUNBUFFERED=1
    command: uvicorn main:app --host 0.0.0.0 --port 8000 --reload

  frontend:
    image: nginx:alpine
    ports:
      - "3000:80"
    volumes:
      - ./frontend:/usr/share/nginx/html:ro
    depends_on:
      - api

volumes:
  swarm_data:
`
        };

        // Init code display
        const codeBlock = document.getElementById('codeBlock');
        function showCode(key) {
            codeBlock.textContent = codes[key];
            codeBlock.className = 'language-' + (key==='main'||key==='swarm' ? 'python' : key==='schema' ? 'sql' : key==='compose' ? 'yaml' : 'html') + ' text-[12px] leading-relaxed block p-6';
            hljs.highlightElement(codeBlock);
            document.querySelectorAll('.code-tab').forEach(t => t.classList.toggle('active', t.dataset.code===key));
        }
        showCode('main');
        document.querySelectorAll('.code-tab').forEach(btn => btn.addEventListener('click', () => showCode(btn.dataset.code)));
        document.querySelector('.copy-btn').addEventListener('click', () => {
            navigator.clipboard.writeText(codeBlock.textContent);
            const b = document.querySelector('.copy-btn'); b.textContent='Copied!'; setTimeout(()=>b.textContent='Copy',1200);
        });

        // Lattice animation
        const canvas = document.getElementById('lattice');
        const ctx = canvas.getContext('2d');
        let latticeMode = 'recall';
        let t = 0;
        function drawLattice(){
            ctx.clearRect(0,0,400,400);
            const size=36, pad=20;
            for(let y=0; y<10; y++){
                for(let x=0; x<10; x++){
                    const i = y*10+x;
                    const px = pad + x*size;
                    const py = pad + y*size;
                    let alpha = 0.2;
                    if(latticeMode==='recall'){
                        alpha = 0.2 + 0.6 * Math.sin(t*0.02 + (x+y)*0.3)**2;
                    } else if(latticeMode==='forge'){
                        alpha = 0.2 + 0.7 * Math.random()* (Math.sin(t*0.05 + i*0.1)>0?1:0.2);
                    } else {
                        alpha = 0.2 + 0.6 * ( ((t + i*7) % 200) < 20 ? 1 : 0 );
                    }
                    ctx.fillStyle = `rgba(${latticeMode==='recall'?139: latticeMode==='forge'?245:16}, ${latticeMode==='socratic'?185:92}, ${latticeMode==='forge'?66:246}, ${alpha})`;
                    ctx.fillRect(px, py, size-4, size-4);
                    ctx.strokeStyle = 'rgba(100,116,139,0.15)';
                    ctx.strokeRect(px, py, size-4);
                }
            }
            t++;
            requestAnimationFrame(drawLattice);
        }
        drawLattice();
        document.querySelectorAll('.lattice-mode').forEach(b => {
            b.addEventListener('click', () => {
                document.querySelectorAll('.lattice-mode').forEach(x => x.classList.replace('bg-violet-500/20','bg-slate-700/50'));
                b.classList.add('bg-violet-500/20'); b.classList.remove('bg-slate-700/50');
                latticeMode = b.dataset.mode;
                document.getElementById('latticeStats').textContent = latticeMode==='recall' ? '66/100 consensus • 4.2ms' : latticeMode==='forge' ? '20/100 mutating • 12.7ms' : 'asking user • socratic';
            });
        });

        // Architecture flow
        const flowLog = document.getElementById('flowLog');
        const flowDot = document.getElementById('flowDot');
        const steps = [
            {node:'frontend', text:'[ASK] user: "what does hold mean?"', pos:[180,50], color:'#22d3ee'},
            {node:'gateway', text:'[ENCODE] text → vector[5] = [0.12, -0.44, 0.81, 0.03, -0.19]', pos:[360,50], color:'#a78bfa'},
            {node:'engine', text:'[RETRIEVE] cosine sim → top 6 neighbors (0.91,0.87,0.84...)', pos:[540,50], color:'#e879f9'},
            {node:'engine', text:'[VOTE] 66 agents sampled → 48 vote [2,2,2], 12 vote [1,1,1], 6 abstain', pos:[540,80], color:'#e879f9'},
            {node:'gateway', text:'[ANSWER] consensus 48/66 = 73% > 66% threshold → return', pos:[360,80], color:'#a78bfa'},
            {node:'db', text:'[STORE] INSERT memory + triple (hold, means, [2,2,2]) ts=...', pos:[720,50], color:'#34d399'},
        ];
        let flowRunning = false;
        document.getElementById('runFlow').addEventListener('click', async () => {
            if(flowRunning) return; flowRunning=true;
            flowLog.innerHTML=''; flowDot.classList.remove('hidden');
            for(let i=0;in.classList.remove('ring-2','ring-violet-500/50'));
                document.getElementById('node-'+s.node)?.classList.add('ring-2','ring-violet-500/50');
                flowLog.innerHTML += `
${s.text}
`; flowLog.scrollTop=flowLog.scrollHeight;
                await new Promise(r=>setTimeout(r,900));
            }
            flowDot.classList.add('hidden'); flowRunning=false;
        });

        // Consensus simulate
        document.getElementById('simulateVote').addEventListener('click', () => {
            const v = 44 + Math.floor(Math.random()*22);
            document.getElementById('consensusBar').style.width = v+'%';
            document.getElementById('consensusLabel').textContent = v+'/100';
        });

        // Triple store
        let tripleId=5;
        document.getElementById('addTriple').addEventListener('click', () => {
            const s = document.getElementById('tripleSubj').value || 'you';
            const p = document.getElementById('triplePred').value || 'mean';
            const o = document.getElementById('tripleObj').value || '[?]';
            const list = document.getElementById('tripleList');
            const div = document.createElement('div'); div.className='flex gap-2';
            div.innerHTML = `${String(tripleId++).padStart(3,'0')}${s}${p}${o}`;
            list.prepend(div);
            document.getElementById('tripleCount').textContent = `${tripleId-1} triples`;
        });

        // Conversational loop
        let loopStep=0; const loopNodes = document.querySelectorAll('#loopNodes circle'); const colors=['#22d3ee','#a78bfa','#a78bfa','#e879f9','#f59e0b','#f59e0b'];
        document.getElementById('stepLoop').addEventListener('click', () => {
            loopNodes.forEach((c,i)=>c.setAttribute('stroke', i===loopStep ? colors[i] : '#334155'));
            loopStep = (loopStep+1)%6;
            const conf = Math.max(0.2, 0.9 - loopStep*0.12 + Math.random()*0.1);
            document.getElementById('confValue').textContent = conf.toFixed(2);
            document.getElementById('confBar').style.width = (conf*100)+'%';
        });
        let modeNormal=true;
        document.getElementById('toggleMode').addEventListener('click', (e) => {
            modeNormal=!modeNormal;
            e.target.textContent = 'Mode: ' + (modeNormal?'Normal':'Socratic');
            e.target.classList.toggle('bg-emerald-600/20', !modeNormal);
        });

        // Deploy button
        document.getElementById('deployBtn').addEventListener('click', () => {
            showCode('compose');
            document.getElementById('starter').scrollIntoView({behavior:'smooth'});
        });

        // Initial highlight
        hljs.highlightAll();