nram

module

v0.0.0-...-aa930a0 Latest Latest Go to latest Published: Aug 3, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/nram-ai/nram

Links

Open Source Insights

README ¶

Last commit

What is it · Get running · Quick Start · Docs · nram.ai

Work in progress: under active development. Expect rough edges, and feedback is welcome.

What is Neural Ram?

Right now, you are the continuity layer between your AI tools. You copy context from Claude into ChatGPT, write handoff docs, re-explain the same decisions, and lose a little more each time you switch tools or machines.

nram takes that job off you. It is one self-hosted server that keeps what mattered across every tool, every conversation, and every machine, on infrastructure that belongs to you. Your agent already reads the PDF, watches the video, runs the test, scrapes the page; nram's job is to keep what mattered. Context, not storage.

It is a real server, not a library or a localhost shim: a single MIT-licensed binary with OAuth, passkeys, multi-tenancy, and MCP over HTTP, so your laptop, desktop, and phone all see the same brain. And it is more than a database with vector search: it pulls facts and entities out of your free-text notes, builds a knowledge graph of how they connect, and runs a background dreaming cycle that consolidates, dedups, and prunes while the server is idle, like a notebook that quietly reorganizes itself overnight.

One substrate, many jobs

nram is not another memory tool bolted onto one app. It is the layer underneath them, so a single server covers work that today is split across separate products:

Job	What nram provides	Comparable tools
Conversational continuity	Memory that survives across sessions, tools, and vendors, reachable over MCP.	Claude Memory, ChatGPT Memory
Document-corpus recall	Semantic search, an entity-deduped knowledge graph, and consolidation over a stored corpus. A substrate, not a chat UI.	NotebookLM, AnythingLLM, Khoj
Procedural rules	A first-class verbatim tier for standing rules, conventions, and protocols an assistant loads at session start. Returned byte-for-byte, never embedded or paraphrased.	(no direct equivalent)
Persona / self-knowledge (`about_me`)	A reserved, fully-indexed tier for identity, preferences, and ongoing context that surfaces by association on every recall.	(no direct equivalent)
Agent memory	Persistent memory for coding, research, and custom agents, with consolidation and a knowledge graph on top.	Mem0, Letta, Zep, Graphiti

Features

Recall that actually finds things

Hybrid vector + lexical search (FTS5 on SQLite, tsvector on Postgres) fused with Reciprocal Rank Fusion and boosted by the knowledge graph.
Relevance-first ranking: query relevance is the base score; priors like recency, importance, and frequency refine the order but never let an off-topic memory outrank the on-topic answer.
MMR de-dup keeps results diverse, and multi-vector facets match a query against a memory's best sub-topic instead of a diluted average.
An optional reranker (cross-encoder /v1/rerank or LLM judge, auto-detected) re-scores the top candidates for relevance.

A knowledge graph that builds itself

Two-pass extraction: background workers pull facts and entities from your free text, then infer the relationships between them.
A closed type vocabulary keeps the graph canonical instead of sprouting near-synonym labels, and a cleanup pass folds duplicate nodes back together.
Query augmentation paraphrases each memory into short retrieval queries so recall matches the way people actually ask.
An optional ingestion judge decides add / update / delete / none against near-duplicates before extraction runs.

Dreaming, an offline consolidation cycle

A fourteen-phase cycle that dedups entities, backfills embeddings and facets, infers transitive relationships, detects contradictions, consolidates, prunes, and recomputes weights while the server is idle.
Consolidation clusters related memories by embedding similarity so syntheses stay coherent, and an LLM novelty audit demotes low-value ones.

Ask: one cited answer, not a list (optional)

Synthesizes a grounded, footnote-cited answer over your memories in a single model call, across every project or one scoped project.
Decomposes aggregation questions per class, gates out off-topic neighbors, and returns "not in neighborhood" rather than fabricating when the answer isn't there.
Off by default behind a feature flag and its own provider slot; prompt-injection-fenced before synthesis.

Tiers built in

Procedural: a verbatim per-user tier for rules and protocols, stored byte-for-byte and never embedded, enriched, or rewritten.
Persona (about_me) and global tiers are reserved, auto-provisioned, and always join the recall aperture.

A real server, not a localhost shim

Auth: OAuth 2.0 (Authorization Code + PKCE, dynamic client registration, resource indicators, discovery), JWT, WebAuthn passkeys, per-org OIDC SSO, and five RBAC roles across REST and MCP.
Multi-tenancy: organizations, hierarchical namespaces, and projects, plus scoped share tokens for access without an account.
Storage: SQLite (zero-config) or PostgreSQL, with pgvector, a pure-Go HNSW index, or Qdrant for vectors, and SQLite-to-Postgres migration tooling.
Provider-agnostic: OpenAI, Anthropic, Google Gemini, Ollama, OpenRouter, vLLM, SGLang, llama.cpp's llama-server, and any OpenAI-compatible endpoint, with per-call token accounting.
Operability: a React Web Console, real-time SSE, HMAC-signed webhooks, Prometheus metrics at /metrics, JSON / NDJSON import/export, and a persistent instance identity (UUID + ES256 keypair) surfaced in nram --version.

How clients connect

MCP is how Claude, ChatGPT, Cursor, or a custom agent connects. Streamable HTTP transport at /mcp, with OAuth discovery at the well-known paths.
REST API lets any code that can speak HTTP store and recall. See docs/api.md.
Web Console is the dashboard for organizations, projects, providers, the knowledge graph, and the dreaming cycle.

Get running

Fastest path is a prebuilt binary (no Go or Node needed). Grab the right archive for your OS from the nightly release, extract it, and run:

./nram

From source:

git clone <repo-url> nram && cd nram
make build      # builds the UI and compiles a single ./nram binary
./nram

Either way, open http://localhost:8674, create the admin account, and save the API key, it is shown only once. A short guided setup then walks you through the required providers, the optional ones, and the high-level feature toggles, one step at a time (nram falls back to keyword-only recall until an embedding provider is configured). You can skip any step and revisit it later under Settings → Providers.

Per-OS download and checksum steps: docs/install.md
Full setup walkthrough, providers, and connecting Claude / ChatGPT / Cursor: docs/quickstart.md

Connect Claude Code in one line:

claude mcp add --transport http nram http://localhost:8674/mcp

Local CLI and IDE tools use the URL directly. Hosted web tools (ChatGPT, claude.ai, the Claude apps) reach your server from the vendor's cloud, so they need a public HTTPS URL via a reverse proxy or tunnel, see docs/quickstart.md.

Run as a service

Run it at boot and restart on failure with the native OS service manager (Windows SCM, Linux systemd, macOS launchd):

sudo ./nram service install     # then: start | stop | restart | status | uninstall

install captures the current directory, --config, and your DATABASE_URL / PORT / LOG_LEVEL / NRAM_CONFIG so the service runs like your shell would. Add --user for a per-user service that needs no root. Full details: docs/operations.md.

Reference

The deep reference is split out to keep this page approachable:

docs/install.md: prebuilt downloads for macOS, Linux, and Windows, and checksum verification.
docs/quickstart.md: build, run, the setup wizard, provider configuration, and connecting a client.
docs/api.md: full REST API and MCP tool reference, including update/supersede and move semantics.
docs/models.md: recommended models per slot, VRAM sizing for local models, the optional reranker, and Ollama num_ctx and keep-alive tuning.
docs/configuration.md: bootstrap vs runtime config, environment variables, databases (SQLite, Postgres, Qdrant), migrations, and operator flags.
docs/operations.md: running as a managed OS service, troubleshooting, and the dreaming / backfill operations guide.
docs/openapi.yaml: OpenAPI 3.1 specification, also served by the running server at GET /openapi.yaml and rendered at GET /docs. A conformance test keeps it in sync with the router.

Development

make install-ui   # install UI dependencies
make dev          # React dev server with hot-reload on port 5173
make build        # build everything into ./nram
./nram --config config.yaml

Repository layout:

cmd/server/        Server entrypoint
internal/
  api/             HTTP handlers (REST + admin)
  auth/            OAuth 2.0, JWT, WebAuthn, RBAC
  config/          Bootstrap configuration loading
  dreaming/        Offline consolidation cycle (fourteen phases) with rollback and retention sweeps
  enrichment/      Background enrichment worker pool, ingestion decision, dedup, re-embed
  events/          Event bus, SSE, webhooks
  mcp/             MCP server and tool handlers
  migration/       Database migration runner
  model/           Data models
  provider/        LLM / embedding provider adapters with token-usage middleware
  server/          HTTP router setup
  service/         Business logic (recall, store, fusion, settings, lifecycle, export jobs)
  storage/         Database repositories (incl. HNSW, pgvector, Qdrant adapters)
  ui/              Embedded Web Console assets
migrations/        SQLite and PostgreSQL migration SQL
ui/                React Web Console source (TypeScript, Tailwind)
docs/              Reference docs and the OpenAPI spec

License

MIT

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
backfill-audit command Command backfill-audit drains the dream novelty-audit backlog for a single project without waiting on the dream scheduler, dirty tracker, cooldown, or min-interval.	Command backfill-audit drains the dream novelty-audit backlog for a single project without waiting on the dream scheduler, dirty tracker, cooldown, or min-interval.
server command
docs Package docs embeds the hand-maintained OpenAPI specification so the server can serve it from the binary at GET /openapi.yaml.	Package docs embeds the hand-maintained OpenAPI specification so the server can serve it from the binary at GET /openapi.yaml.
internal
api
auth
cluster Package cluster provides a small, deterministic cosine-clustering primitive shared across the codebase.	Package cluster provides a small, deterministic cosine-clustering primitive shared across the codebase.
config Package config holds the bootstrap configuration for the nram server.	Package config holds the bootstrap configuration for the nram server.
dreaming Package dreaming provides the background "dreaming" system that cross-references memories within a project to improve the knowledge graph.	Package dreaming provides the background "dreaming" system that cross-references memories within a project to improve the knowledge graph.
enrichment Package enrichment provides background worker pool processing for the nram enrichment pipeline.	Package enrichment provides background worker pool processing for the nram enrichment pipeline.
events
instructions Package instructions holds all three tiers of nram's agent memory-usage guidance in one directory so they can be read side by side and diffed.	Package instructions holds all three tiers of nram's agent memory-usage guidance in one directory so they can be read side by side and diffed.
logging Package logging provides the unified diagnostic-logging abstraction that all of nram's structured logging flows through.	Package logging provides the unified diagnostic-logging abstraction that all of nram's structured logging flows through.
maintenance Package maintenance provides a small, backend-agnostic registry of in-flight maintenance operations that degrade server performance while they run (for example a SQLite VACUUM).	Package maintenance provides a small, backend-agnostic registry of in-flight maintenance operations that degrade server performance while they run (for example a SQLite VACUUM).
mcp
migration
model
netutil Package netutil holds small, dependency-free network primitives shared by packages that would otherwise each carry their own copy.	Package netutil holds small, dependency-free network primitives shared by packages that would otherwise each carry their own copy.
observability/metrics Package metrics owns the Prometheus instrumentation surface for nram: the metric definitions, the chi middleware that records HTTP timings, and the /metrics handler.	Package metrics owns the Prometheus instrumentation surface for nram: the metric definitions, the chi middleware that records HTTP timings, and the /metrics handler.
periodic Package periodic provides a single background-loop primitive shared by every DB-maintenance sweeper: run a sweep once at startup, then again on a re-resolved interval, until the context is cancelled.	Package periodic provides a single background-loop primitive shared by every DB-maintenance sweeper: run a sweep once at startup, then again on a re-resolved interval, until the context is cancelled.
provider Package provider defines the core interfaces and types for LLM and embedding providers used throughout the nram enrichment pipeline.	Package provider defines the core interfaces and types for LLM and embedding providers used throughout the nram enrichment pipeline.
recallview Package recallview holds the canonical per-memory shape for the recall response and the single projection that produces it.	Package recallview holds the canonical per-memory shape for the recall response and the single projection that produces it.
repopath Package repopath locates the repository root at runtime so build tooling and tests can resolve module-relative files (for example docs/openapi.yaml) regardless of the working directory they run in.	Package repopath locates the repository root at runtime so build tooling and tests can resolve module-relative files (for example docs/openapi.yaml) regardless of the working directory they run in.
server
service
storage
storage/admin
storage/hnsw
tags Package tags provides tag-string normalization shared across service write paths and one-shot storage backfills.	Package tags provides tag-string normalization shared across service write paths and one-shot storage backfills.
ui
version Package version is the single source of truth for the nram build identity.	Package version is the single source of truth for the nram build identity.
migrations
scripts
appicon/genico command Command genico packs one or more PNG images into a single multi-size Windows .ico file, storing each image as a PNG payload (the format Windows Vista and later understand for icon resources).	Command genico packs one or more PNG images into a single multi-size Windows .ico file, storing each image as a PNG payload (the format Windows Vista and later understand for icon resources).
gen_openapi_setting_keys command Command gen_openapi_setting_keys regenerates the SettingKey enum in docs/openapi.yaml from the canonical Go settings registry (admin.SettingsSchemas) so the OpenAPI spec always lists every known setting key.	Command gen_openapi_setting_keys regenerates the SettingKey enum in docs/openapi.yaml from the canonical Go settings registry (admin.SettingsSchemas) so the OpenAPI spec always lists every known setting key.