known

known

A persistent memory graph for LLMs. Store facts during one session, recall them in the next.

LLM agents lose context between sessions. Decisions, environment details, codebase conventions, user preferences — all gone after compaction. known is a local knowledge graph that persists across sessions, so agents stop re-learning the same things.

How it works

Session 1: user says "we use ULIDs, not UUIDs"
  → known add 'All new tables use ULIDs instead of UUIDs' --source-type conversation

Session 2: agent is about to generate a migration
  → known recall 'ID generation strategy'
  → gets: "All new tables use ULIDs instead of UUIDs" [verified, root scope]
  → generates the migration correctly without asking

Entries are stored with vector embeddings for semantic search, organized into hierarchical scopes, and connected by typed edges (depends-on, contradicts, supersedes, elaborates, related-to).

Install

Requires Go 1.25+.

go install github.com/dpoage/known/cmd/known@latest

Or build from source:

git clone https://github.com/dpoage/known.git
cd known
go build -o known ./cmd/known/

No CGo required. The default embedder (hugot) and database (SQLite) are both pure Go.

Quick start

# Initialize a project — creates .known.yaml and Claude Code skills
known init

# Store a fact
known add 'The API uses JWT tokens with RS256 signing' \
  --source-type conversation --confidence verified

# Recall knowledge (LLM-optimized plain text output)
known recall 'authentication'

# Search with scores and IDs
known search 'authentication' --limit 5

# See what's stored
known stats
known scope tree

Claude Code integration

known init scaffolds Claude Code skills and a session-start hook into .claude/:

Skill	Purpose
/remember	Store a fact from the conversation
/recall	Retrieve knowledge for a query
/forget	Find and delete an entry
/known-search	Search with full flag control

The session-start hook injects the scope tree into context, so the agent knows what knowledge areas exist without loading content upfront.

Architecture

cmd/            CLI commands (init, add, recall, search, ...)
cmd/scaffold/   Embedded Claude Code skill templates
model/          Core types: Entry, Edge, Scope, ID (ULID)
storage/        Backend interface + implementations
  sqlite/       Default — pure Go transpiled from C, no CGo
  postgres/     PostgreSQL + pgvector for production scale
query/          Search engine: vector, graph traversal, hybrid
embed/          Embedder interface + backends
  hugot         Default — pure Go ONNX inference, zero config
  ollama        Local Ollama server
  openai        OpenAI-compatible APIs (OpenAI, Azure, vLLM, etc.)

Storage

The default backend is SQLite with in-process vector search. Entries, edges, and scopes are stored in a single file at ~/.known/known.db. Each project can override the DSN in its .known.yaml for a per-project database.

PostgreSQL with pgvector is supported for production deployments.

Embeddings

The default embedder is hugot — pure Go ONNX inference using sentence-transformers/all-MiniLM-L6-v2. The model is downloaded to ~/.known/models/ on first use. No API keys, no external services.

For faster embeddings or larger models, configure an external provider:

# Ollama
export KNOWN_EMBEDDER=ollama
export KNOWN_EMBED_URL=http://localhost:11434
export KNOWN_EMBED_MODEL=nomic-embed-text

# OpenAI-compatible
export KNOWN_EMBEDDER=openai-compatible
export KNOWN_EMBED_URL=https://api.openai.com
export KNOWN_EMBED_API_KEY=sk-...
export KNOWN_EMBED_MODEL=text-embedding-3-small

Scopes

Scopes are hierarchical namespaces derived from directory structure. Working in ./backend/api/ auto-derives scope backend.api. Searching a scope includes all descendants — searching backend returns results from backend.api, backend.storage, etc.

Projects sharing the same database (the default) can recall across project boundaries by specifying the other project's scope: known recall 'auth' --scope otherproject.

Commands