Open Source · Self-Hosted · Privacy-First · Local by Default

One brain.
Every agent.
Nothing forgotten.

A self-hosted personal memory layer for AI agents — built on Postgres, pgvector and MCP.
Runs 100% local by default. No API keys. No cloud dependency. Your data never leaves your machine.
You are a software developer? ✦ Try Aperio-dev — basic terminal comfort is required.
You are a normal human? ✦ Try Aperio-lite — double-click and go, no tech skills needed.

Download Aperio-dev Download Aperio-lite View on GitHub

Postgres 16 LanceDb pgvector MCP Protocol Ollama Local Embeddings

aperio — local · private · yours

🤖 Provider: Ollama (deepseek-r1:7b)

✅ Connected to Aperio database

✅ pgvector enabled — semantic search active (16/16 memories embedded)

🧠 Aperio MCP server v2.0 running

✅ MCP server connected

You › what's my preferred stack?

[recall] searching memories… cosine similarity 0.94

A › Based on your memories:

› Language: TypeScript

› Backend: Node · Postgres · Docker

› Editor: Cursor with MCP enabled

You › remember I switched to pnpm

🔭 Listening on port 31337 — the original l33t port. Famous in the 90s, introduced by the group 'Cult of the Dead Cow' in 1998, a ghost town on modern machines today. Ours now. Too iconic not to use! He-he ;/

Features

Everything you need.
Nothing you don't.

Built for developers who want AI that actually knows them. Without giving up their data or their infrastructure.

Persistent Memory

Memories survive every conversation, every tool, every session. 7 structured types keep things organized — facts, decisions, solutions and more.

Semantic Search

Powered by pgvector + local embeddings (mxbai-embed-large). Ask about your projects and get results matched by meaning, not keywords. Voyage AI optional.

MCP Native

One brain shared across every agent. Claude, Cursor, Windsurf — all connect to the same Postgres database through the MCP protocol.

Real-time Streaming

Responses stream token by token via WebSocket. Live code rendering, markdown on completion, smart auto-scroll. No waiting.

Local by Default

Runs fully on your machine with Ollama — free, private, offline-capable. Switch to Claude with one env variable when you need more power.

Auto Deduplication

Background job finds near-duplicate memories every 10 minutes using cosine similarity. Dry-run by default — you stay in control.

Reasoning Models

Native support for thinking models — qwen3, deepseek-r1. A collapsible reasoning bubble shows the model's thought process live. Toggle it on or off anytime.

Team Ready

Since you own the database, Aperio scales from personal to shared team brain with two changes — update the system prompt and seed team memories. One brain for the whole team.

Architecture

Simple stack.
Serious power.

One database. One MCP server. Two AI providers. Your brain is just a Postgres table with vectors.

aperio / system architecture

🌐

Web UI

localhost:31337 · 4 themes · streaming

↕ WebSocket

⚡

Express Server

server.js · agent loop

↕ stdio

🔧

MCP Server

mcp/index.js · 11 tools

↕

🐘

Postgres 16 + pgvector

memories table · HNSW index

↕

⬡

Ollama Embeddings

mxbai-embed-large · 1024 dims · zero external calls

✦

Voyage AI

optional · voyage-3 · 1024 dims · cloud upgrade

AI Providers

⬡

Ollama

default · local · free · offline capable

✦

Claude API

optional · cloud upgrade · haiku · sonnet · opus

Memory Types

factpreference projectdecision solutionsourceperson

MCP Tools

11 tools. One brain.

Every tool is available to any MCP-compatible agent (Claude, Cursor, Windsurf).
Memory ops, file ops, web fetching.

remember

Save a memory with auto-generated embedding

recall

Semantic search with cosine similarity scores

update_memory

Edit by UUID, regenerates embedding automatically

forget

Delete a specific memory by UUID

backfill_embeddings

Generate missing embeddings in batch

dedup_memories

Find near-duplicates via cosine similarity

read_file

Read any file from disk (max 500 lines)

write_file

Overwrite a file completely with absolute paths

append_file

Add to end of file with before/after verification

scan_project

Scan folder tree up to 3 levels deep

fetch_url

Fetch a URL, strip HTML, truncate to 15k chars

Team Ready out of the box

Personal brain.
Or shared team brain.
You decide.

Aperio is personal by default.
But since you own the database, it can become a shared team brain with minimal changes.
Every agent, every teammate, every tool — all drawing from the same memory pool.

📋

Shared Decisions

"We chose Fly.io over Railway in Q3 2024 because of better pricing for always-on workloads."

🗂️

Project Knowledge

"Project Atlas uses Next.js, PlanetScale, and Stripe. PM is Sara. Lead dev is John."

🚀

Onboarding

"New devs should read X, set up Y, ask Z about access. Deploy on merge to main."

📖

Runbooks

"When the DB goes down: check pgvector index first, then connection pool, then restart."

👥

People Context

"John handles DevOps, prefers async comms, UTC+2. Sara owns the product roadmap."

🔍

Cross-Project Search

"Which projects use Stripe?" · "Who owns the analytics pipeline?" · "What's our infra stack?"

team setup — 2 changes only

1. Update prompts/system_prompt.md

You are a helpful team assistant with access to Aperio
— a shared memory system that stores context
about your team, projects, and decisions.

2. Seed team memories in 001_init.sql

INSERT INTO memories (type, title, content)
VALUES
  ('project', 'Atlas', 'Next.js + PlanetScale...'),
  ('person', 'Sara', 'PM for Atlas...'),
  ('decision', 'Fly.io', 'Chosen Q3 2024...');

Extensibility

Build on top.
Make it yours.

Aperio is a foundation, not a finished product. The source is fully open — fork it, extend it, repurpose it.
Here's what you can build on top.

Memory Layer

Custom Memory Types

The schema is yours to extend. Add new memory types, extra metadata columns, TTL logic, or per-project namespacing. Postgres gives you full flexibility.

mood_log habit_tracker meeting_note code_snippet bookmark

MCP Layer

New MCP Tools

Adding a tool is just a new entry in mcp/index.js. Expose calendar access, email drafting, browser control — any action you want your agents to take.

calendar_tool send_email run_tests git_commit deploy

AI Layer

Swap the Embedding Model

mxbai-embed-large via Ollama is the default — zero external calls. Swap in Voyage AI for higher quality, or drop in OpenAI, Cohere, or any provider with a vectors API.

openai/text-embedding-3 cohere-embed nomic-embed-text

UI Layer

Replace or Extend the UI

The web interface is a standalone HTML file with WebSocket. Rip it out and build a VS Code extension, a mobile app, a CLI, a Chrome sidebar — the server API stays the same.

vscode extension raycast plugin mobile app chrome sidebar

Data Layer

Memory Analytics & Insights

Query your own memory graph. Build dashboards showing what topics you think about most, decision patterns over time, knowledge gaps, or memory growth by week.

knowledge graph memory heatmap topic clusters decay scoring

Team Layer

Team Shared Memory

Since you own the database, Aperio scales from personal to team brain with two changes: update the system prompt to team context, seed team memories in 001_init.sql.

shared decisions project knowledge onboarding runbooks

Agent Layer

Multi-Agent Memory Sharing

Run multiple specialized agents that all share one brain. A research agent stores findings, a coding agent reads context, a writing agent pulls preferences — all from the same database.

research agent coding agent shared context team memory

Got an idea? Build it and share it.

Open a PR, open an issue, or fork it and take it somewhere new. Aperio is a starting point.

Fork on GitHub

Why Aperio

Your data. Your rules.

Commercial memory services are great products.
Aperio is a different choice — self-hosted, open source, fully customizable.

Feature	✦ Aperio	Cloud Services
Data ownership	✅ 100% yours — own Postgres	✗ Vendor's servers
Monthly cost	✅ Free (self-hosted)	✗ $20–100 / month
Local AI support	✅ Ollama built-in	✗ Cloud only
File system tools	✅ read · write · append	✗ Not available
Full source access	✅ Open source — fork it	✗ Closed API
MCP integration	✅ Native protocol	⚠ Varies
Works offline	✅ With Ollama	✗ Requires internet
Non-developer friendly	✅ Aperio-lite — double-click & go	✗ Requires dev setup
Team memory	✅ Shared DB — one brain for the team	⚠ Varies by plan

Web UI

See it in action.

Local AI · persistent memory · streaming responses · 4 themes.

Aperio Web UI — chat interface with memory sidebar

Quick Start

Up in 5 minutes.

Node 18+, Docker, and Ollama. No API keys. No cloud. 100% local.
Or add Claude + Voyage AI when you need more power.

01

Clone & install dependencies

# dedicated developer branch - no extra files

git clone --depth 1 -b dev https://github.com/BaiGanio/aperio.git

cd aperio

# install dependencies

npm install

02

Ready for use .env.example in the project folder

DATABASE_URL=postgresql://aperio:xxx-xxx-xxx
AI_PROVIDER=ollama
OLLAMA_MODEL=llama3.1:8b
EMBEDDING_PROVIDER=ollama
OLLAMA_EMBED_MODEL=mxbai-embed-large

03

Databases

# Vector database for lite mode when Docker is not in use

npm install @lancedb/lancedb uuid

cd docker

docker compose up -d

cd ..

# run migrations

docker exec -i aperio_db psql -U aperio -d aperio < db/migrations/001_init.sql

docker exec -i aperio_db psql -U aperio -d aperio < db/migrations/002_pgvector.sql

04

Pull the models

# start the engine from separate terminal

ollama serve

# best LLM on low budget

ollama pull llama3.1:8b

Available options:

lite - qwen2.5:3b (~4GB RAM, ~2GB disk)

medium - llama3.1:8b (~8GB RAM, ~5GB disk)

smart - qwen3:8b (~10GB RAM, ~5GB disk)

reasoning - qwen3:14b (~16GB RAM, ~9GB disk)

pro - deepseek-r1:32b (~32GB RAM, ~19GB disk)

# embeddings — local semantic search

ollama pull mxbai-embed-large

05

Launch Aperio Web UI

# start from the project root

# opens at localhost:31337

npm run start:local

# cloud (Claude) -> localhost:3000

# npm run start:cloud

06

Use Aperio chat in the terminal

# local (Ollama)

# Feat: auto-detect if Docker is stopped - uses LanceDb as fallback

npm run chat:local

# cloud (Anthropic)

npm run chat:cloud

✅ Tip: Check out project README.mdfor extensive documentation, troubleshooting, and advanced configuration options.

Aperio-lite · For non-code humans

Small tool. Big ideas. 🧐
No coding skills required.


      The fastest path to your own private AI.

      Runs 100% on your machine. No Money. No Cloud. No register your email here and there.

      Download → unzip → double-click. That's it.
    

    
    
       Double-click Launch
       macOS
       Linux
       Windows
       Delete to uninstall
    

    
    
       the whole flow — once is enough
      
        📥 Download
        →
        📂 Unzip
        →
        🔗 Make Alias / Shortcut
        →
        🖥️ Drop on Desktop
        →
        Double-click → (one-time) setup
        →
        Browser opens automatically
      
    

    
    

        
        
           macOS
          
            1. Download, unzip, open in Finder
            2. Look for folder called how-to-install → double-click it
            3. Find START.sh → right-click → Make Alias
            4. Rename the alias to Aperio
            5.A Drag alias to Desktop folder in Finder's sidebar
            ❗ Sidebar item — not the Desktop surface itself
            5.B Hold ⌥ Option + ⌘ Cmd and drag START.sh directly onto the desktop → rename it there
            6. Double-click → one-time setup → done
            ✅ Default browser opens automatically at
http://localhost:31337
            
          
        

        
        
           Windows
          
            1. Download, unzip, open in File Explorer
            2. Look for folder called how-to-install → double-click it
            3. Find START.bat → right-click → Rename
            4. Rename the file to Aperio.bat
            5.A Move shortcut to Desktop
            5.B Hold Alt and drag START.bat directly onto the desktop → rename it there
            6. Double-click → one-time setup → done
            ✅ Default browser opens automatically at
 http://localhost:31337
            
          
        

        
        
           Linux
          
            1. Download, unzip, open in your file manager
            2. Look for folder called how-to-install → open it
            3. Find START.sh → right-click → Properties → Permissions
            4. Enable Allow executing file as program → close
            5. Right-click START.sh → Copy to Desktop → rename to Aperio
            ❗ Menu labels vary by distro (Nautilus, Dolphin, etc.)
            6. Double-click → one-time setup → done
            ✅ Default browser opens automatically at
 http://localhost:31337
            
          
           

        
        
          No tech skills required
          
            Nothing to configure.
            ✅ No databases to set up.
✅ No config files to edit.
✅ No environment variables.
✅ No package managers.
            
            Just download and double-click.
            First run installs everything automatically in the background.
You'll see a terminal window — that's normal.
 The terminal is yours GOD EYE on what is happening.
            
          
        

        
        
          Feature updates
          
            Download the latest release.
            ✅ Windows
- Right-click on the zip and select "Extract All..."
- In the dialog, specify your aperio-lite folder.
✅ macOS/Linux (Terminal - fastest)
- unzip aperio-lite.zip -d ~/aperio-lite
            
            Your data stays untouched.            
            
            ❗ Might want to export your memories first.
            - You'll have your data even if the update fails
            
          
        

        
        
          subsequent runs & Uninstall
          
            Every run after the first run?
            Double-click the desktop shortcut. That's it.
            Terminal: ./start.sh
            ✅ If you can open a browser, you can run Aperio.
            
            How to remove it if I do not like it?
            1. Delete the Desktop alias / shortcut
            2. Delete the unzipped folder
            ✅ That's it. Completely gone.
- No registry entries. No hidden files.
- No traces. Nothing.
            
          
        
    
  
    
   
      
         Download Aperio-lite
      
      
         I prefer the terminal

One brain. Every agent. Nothing forgotten.

Everything you need.Nothing you don't.

Simple stack.Serious power.

11 tools. One brain.

Personal brain.Or shared team brain.You decide.

Build on top.Make it yours.