Neron-DB

The data shape of Neron, packaged as a single bootstrap.sql + builder docs so you can spin up a Neron-style memory backend and write your own MCP servers (or any product) on top of it.

---

What is this?

Neron is a memory-and-context system that captures voice/text notes, extracts structured entities (moods, tasks, people, reflections, …), and stores cross-references in a graph. After a year in production we've converged on a data shape that pairs:

• a PostgreSQL relational schema (14 tables) for entity content, and
• an Apache AGE property graph (10 vertex labels, 10 edge types) for many-to-many relationship metadata.

Neron-DB is that shape, extracted from the production codebase and stripped of multitenant/auth/Telegram-specific machinery so a single person can run it on a laptop in 5 minutes and start building.

Why builders care

You can build:

• Personal memory products — journaling, life-logging, "second-brain" apps with semantic search out of the box.
• Vertical CRMs — N:N person mentions with per-mention context/confidence/interaction-type are CRM primitives.
• Agent backends — every entity is reachable as both a relational row and a graph vertex, so agents can JOIN or traverse depending on the question.
• Custom MCP servers — drop the 9 tool blueprints into any language and ship.

Quickstart

# 1. Get a Postgres+AGE+pgvector environment (Docker example).
docker run --name neron-db -e POSTGRES_PASSWORD=neron \
  -p 5432:5432 -d apache/age:release_PG16_1.6.0

# 2. Bootstrap.
docker exec -u postgres neron-db psql -c "CREATE DATABASE neron_demo;"
docker exec -u postgres neron-db psql -d neron_demo \
  -c "CREATE SCHEMA myapp;"
docker exec -i -u postgres neron-db psql -d neron_demo \
  -c "SET search_path = myapp, public;" -f - < bootstrap.sql

# 3. Verify.
docker exec -u postgres neron-db psql -d neron_demo \
  -c "\dt myapp.*" \
  -c "SELECT name FROM ag_catalog.ag_graph;"

For local Postgres or troubleshooting, see docs/00-quickstart.md.

Data shape — relational

erDiagram
    neron ||--o| moods : "1:1"
    neron ||--o| bodies : "1:1"
    neron ||--o| foods : "1:1"
    neron ||--o{ activities : "1:N"
    neron ||--o{ reflections : "1:N"
    neron ||--o{ resources : "1:N"
    neron ||--o{ extraction_traces : "1:N"
    neron ||--o{ extraction_log : "1:N"
    neron ||--o{ tasks : "origin"
    ai_notes ||--o{ tasks : "origin"
    projects ||--o{ tasks : "container"
    neron {
        int id PK
        text content
        vector embedding
        timestamptz timestamp
    }
    ai_notes {
        int id PK
        text content
        date day "DayNote"
        text note_type
    }
    people {
        int id PK
        varchar name UK
        vector embedding
    }
    projects {
        int id PK
        varchar name
        varchar status
    }
    tasks {
        int id PK
        varchar title
        int project_id FK
        int note_id FK
        int ai_note_id FK
    }
    user_settings {
        varchar setting_key UK
        jsonb setting_value
    }

Loading

(people has no FK back to neron — Note↔Person is N:N and lives in the graph layer below.)

Data shape — AGE graph

flowchart LR
    Note -->|HAS_MOOD| Mood
    Note -->|HAS_BODY| Body
    Note -->|HAS_FOOD| Food
    Note -->|HAS_ACTIVITY| Activity
    Note -->|HAS_REFLECTION| Reflection
    Note -->|HAS_TASK<br/>+ context, confidence| Task
    Note -->|MENTIONS_PERSON<br/>+ context, confidence,<br/>interaction_type| Person
    Note -->|AFTER| Note2[Note]
    Note -->|ON_DAY| DayNote
    Task -->|PART_OF| Project
    AINote

Loading

Vertex labels carry a single identity property (note_id, ai_note_id, or entity_id) — see docs/02-age-graph.md. Per-mention metadata lives on the edges, not the vertices, not the relational rows — see docs/03-rules.md rule 2.

Documentation

Doc	Purpose
00-quickstart.md	Get a running database + smoke tests in 5 minutes.
01-tables.md	Per-table reference: every column, index, FK.
02-age-graph.md	Vertex labels, edge types, write paths, query patterns.
03-rules.md	The 9 invariants you must internalize before writing code.
04-mcp-tools.md	Nine MCP tool blueprints with simplified SQL + Cypher.
05-extending.md	Adding tables, edge types, multi-tenancy.
06-embeddings.md	Default voyage-3 + dim 1024; how to swap models / index.

Standalone Cypher snippets live in cypher/.

What's not in this repo

• Auth / OAuth / per-user role switching — the official Neron MCP uses OAuth 2.1 + per-user PostgreSQL roles, but that's one valid pattern, not part of the data contract. Pointer in 05-extending.md.
• Reference MCP server implementation — that'll live in a sibling repo (Neron-Org/neron-mcp, eta TBD). See examples/README.md.
• Telegram-specific tables (chat_threads, pending_extractions, …) — excluded as platform-coupled UX state.
• Telemetry pipeline (Loki / Prometheus / shared.events) — out of scope for the data shape.

Compatibility & versioning

This is v1 of the schema. Breaking changes to table shapes will be called out in CHANGELOG.md and bumped major. Additive changes (new tables, new edge types, new columns) are minor.

The schema follows production NeronApp on the Neron-Org/neron-app main branch, with a small set of deliberate omissions (multitenant + Telegram + legacy relational mirrors).

License

MIT — see LICENSE. Apache AGE (Apache-2.0) and pgvector (PostgreSQL license) are dependencies but not redistributed by this repository.