tesseract

README

Tesseract

Tesseract is a local-first context, memory, and knowledge service for people, tools, and AI agents. It keeps append-only revision history, applies namespace and capability policy, and exposes the same store through a Go library, CLI, HTTP API, embedded web UI, and MCP server.

Tesseract is currently a public preview. Its contracts are documented and tested, but pre-1.0 releases may contain breaking changes. Read CHANGELOG.md before upgrading.

What it provides

• revisioned context records with deterministic heads and history
• separate memory and pointer-backed knowledge domains
• namespace ownership and scoped capability tokens
• explicit request, approval, and apply stages for cross-namespace promotion
• lexical recall plus optional OpenAI-backed embeddings and synthesis
• a local operator UI embedded in the Go binary
• integrity-checked, failure-atomic store backup and restore

Install from source

The current preview is distributed as source. There are no supported prebuilt binaries, package-manager formulae, container images, or desktop installers.

Requirements:

• Go 1.26.6
• Git
• Node.js 20.19–20.x or 22.12+ with npm only when changing and rebuilding frontend/

git clone https://github.com/hollis-labs/tesseract.git
cd tesseract
make build
./tesseract --version

make build compiles the committed web UI bundle and needs only Go. Use make install to install the binary into your Go bin directory. Frontend contributors use make build-all or regenerate the embedded bundle explicitly.

Quick start

Inspect the paths Tesseract will use before creating data:

./tesseract path

Start the daemon:

./tesseract serve

The default listener is http://127.0.0.1:8089: loopback-only and unauthenticated. The API is under /v1/, and the web UI is at /.

In another terminal, write and read a context record:

./tesseract context put \
  --client-id demo \
  --namespace app/demo/session \
  --key goal \
  --actor app:demo \
  --json '{"objective":"evaluate tesseract"}'

./tesseract context get \
  --namespace app/demo/session \
  --key goal

Provider credentials are optional. Core context, memory, knowledge, lexical recall, CLI, HTTP, UI, and MCP workflows work without them. To enable embeddings or synthesis, copy one of the sample configs to the config-file reported by tesseract path and set the matching environment variables:

• examples/config.openai.yaml
• examples/config.anthropic-openai.yaml
• env.example

Provider-backed features transmit selected content to the configured provider. Review the data egress table before enabling them.

The complete first-run flow is in docs/QUICKSTART.md.

Network and authentication boundary

Tesseract refuses an unauthenticated non-loopback bind unless the operator uses the explicit --allow-unauthenticated-remote override. For remote access, choose managed authentication or a static token:

# Create a managed token before starting managed-auth mode.
./tesseract context token create \
  --name remote-client \
  --client-id app:remote-client \
  --scopes write,promote.request,packet \
  --namespaces 'app/remote-client/*' \
  --ttl 24h

./tesseract serve --managed-auth --addr 0.0.0.0:8089

export TESSERACT_TOKEN='replace-with-a-long-random-token'
./tesseract serve --static-token "$TESSERACT_TOKEN" --addr 0.0.0.0:8089

When either token mode is active, every HTTP route requires Authorization: Bearer <token> except readiness and the optional metrics endpoint. A static token deliberately has no admin scope. Mutating the runtime settings or its config backups therefore requires managed auth and a managed token created with the explicit admin scope.

Authentication is not transport encryption. Tesseract has no built-in TLS; put any remotely reachable listener behind TLS, a VPN, an SSH tunnel, or a trusted TLS-terminating reverse proxy. See SECURITY.md.

MCP

Tesseract can run as an MCP stdio server; a separate HTTP daemon is not required:

./tesseract mcp --token '<capability-token>'

Use examples/mcp.json as a client configuration starting point. The token controls mutations, memory/knowledge read scopes, and some namespace filtering, but it is not a complete read-isolation boundary for the local stdio server. See docs/AGENT-SETUP.md and docs/MCP_TOOLS.md.

Backup before real use

A current backup is a directory containing a whole-database snapshot, record payloads, and a checksummed manifest. Configuration is included only when --config is supplied.

./tesseract context backup export \
  --out "$PWD/tesseract-backup" \
  --config /path/reported/by/tesseract-path/config.yaml

./tesseract context backup verify --in "$PWD/tesseract-backup"

Stop every daemon and MCP process that uses the store before restoring. Restore replaces the destination; it does not merge. Detailed recovery and upgrade guidance is in docs/OPERATIONS.md.

Documentation

• docs/README.md — documentation index
• docs/QUICKSTART.md — installation and first run
• docs/AGENT-SETUP.md — MCP client setup
• docs/OPERATIONS.md — support, auth, egress, backup, and upgrades
• docs/ARCHITECTURE.md — storage and service design
• docs/SPECS/API.md — HTTP contract
• docs/SPECS/CLI.md — CLI contract
• docs/MCP_TOOLS.md — MCP tool catalog
• SECURITY.md — security policy and deployment boundary
• CONTRIBUTING.md — contribution workflow

Develop

make test
make validate
go vet ./...

See CONTRIBUTING.md for the complete contributor checks.

License

Tesseract is released under the MIT License.

Documentation

Index

• Variables
• func NewEmbedHandler(memStore *memory.Store, model string, logger func(string, ...any)) queue.Handler
• type Config
• type Option
  • func WithDedupThreshold(t float64) Option
  • func WithEmbedder(e embedcontracts.Embedder) Option
  • func WithEmbeddingModel(model string) Option
  • func WithLogger(fn func(string, ...any)) Option
  • func WithQueue(q queue.Queue) Option
• type SearchOptions
• type Tesseract
  • func Open(ctx context.Context, cfg Config, opts ...Option) (*Tesseract, error)
  • func (c *Tesseract) Close() error
  • func (c *Tesseract) Embed(ctx context.Context, recordID string) error
  • func (c *Tesseract) EmbedRevision(ctx context.Context, revisionID string) error
  • func (c *Tesseract) GetCurrentRevision(ctx context.Context, namespace, key string) (memory.Revision, error)
  • func (c *Tesseract) GetRevisionHistory(ctx context.Context, namespace, key string) ([]memory.Revision, error)
  • func (c *Tesseract) MemoryStore() *memory.Store
  • func (c *Tesseract) RecallMemory(ctx context.Context, in memory.RecallInput) ([]memory.RecallResult, error)
  • func (c *Tesseract) Search(ctx context.Context, query string, opts SearchOptions) ([]embedding.SearchResult, error)
  • func (c *Tesseract) Store() *contextstore.Store
  • func (c *Tesseract) WriteMemory(ctx context.Context, in memory.WriteInput) (memory.Revision, error)

Variables

var ErrEmbedderUnavailable = memory.ErrEmbedderUnavailable

ErrEmbedderUnavailable is returned when an embedding operation is attempted but no embedder has been configured on the Tesseract instance. It is the same sentinel exposed by memory.ErrEmbedderUnavailable.

Functions

func NewEmbedHandler

func NewEmbedHandler(memStore *memory.Store, model string, logger func(string, ...any)) queue.Handler

NewEmbedHandler returns a queue.Handler that processes embed jobs. The handler decodes the revision ID from the job payload and calls EmbedRevision on the memory store to generate and persist the embedding.

Types

type Config

type Config struct {
	// RootDir is the base directory of the tesseract data layout. When DBPath
	// and RecordsDir are empty, the main database and JSON record tree are
	// derived under RootDir/data/ — the layout embedded consumers (nanite,
	// tesseract lib v0.7.0) rely on. RootDir is always required.
	RootDir string

	// DBPath, when set, is the explicit path to the main context database,
	// overriding the RootDir/data/index/context.db derivation.
	//
	// RecordsDir, when set, is the explicit JSON record tree, overriding
	// RootDir/data/records.
	//
	// These let a go-apppaths-resolved caller (cmd/tesseract, cmd/smoke) point
	// the library at the XDG layout without changing default behavior for
	// RootDir-only consumers. Added for the go-apppaths migration
	// (CW-20260517-0066).
	DBPath     string
	RecordsDir string
}

Config holds the top-level configuration for a Tesseract instance.

type Option

type Option func(*options)

Option is a functional option for Open.

func WithDedupThreshold

func WithDedupThreshold(t float64) Option

WithDedupThreshold sets the similarity threshold for semantic dedup.

func WithEmbedder

func WithEmbedder(e embedcontracts.Embedder) Option

WithEmbedder sets the embedding provider used for vector indexing.

func WithEmbeddingModel

func WithEmbeddingModel(model string) Option

WithEmbeddingModel sets the model name passed to the embedder.

func WithLogger

func WithLogger(fn func(string, ...any)) Option

WithLogger sets a custom log function (defaults to log.Printf).

func WithQueue

func WithQueue(q queue.Queue) Option

WithQueue sets the background job queue used for async embedding. When set, a worker is started automatically and a QueueAdapter is used instead of the default NoopQueue.

type SearchOptions

type SearchOptions struct {
	Limit      int
	Threshold  float64
	Namespaces []string
	Types      []string
}

SearchOptions controls the behavior of a Search call.

type Tesseract

type Tesseract struct {
	// contains filtered or unexported fields
}

Tesseract is the top-level library handle. Create one via Open().

func Open

func Open(ctx context.Context, cfg Config, opts ...Option) (*Tesseract, error)

Open creates a Tesseract instance rooted at cfg.RootDir, initializing the SQLite store, memory subsystem, and decay goroutine.

func (*Tesseract) Close

func (c *Tesseract) Close() error

Close stops the decay goroutine and closes the underlying store.

func (*Tesseract) Embed

func (c *Tesseract) Embed(ctx context.Context, recordID string) error

Embed generates and stores a vector embedding for the record identified by recordID. It fetches the record from the store, extracts embeddable text, calls the configured embedder, and upserts the resulting vector.

func (*Tesseract) EmbedRevision

func (c *Tesseract) EmbedRevision(ctx context.Context, revisionID string) error

EmbedRevision generates and stores an embedding for a memory revision.

func (*Tesseract) GetCurrentRevision

func (c *Tesseract) GetCurrentRevision(ctx context.Context, namespace, key string) (memory.Revision, error)

GetCurrentRevision returns the current revision for a namespace/key pair.

func (*Tesseract) GetRevisionHistory

func (c *Tesseract) GetRevisionHistory(ctx context.Context, namespace, key string) ([]memory.Revision, error)

GetRevisionHistory returns all revisions for a namespace/key pair, newest first.

func (*Tesseract) MemoryStore

func (c *Tesseract) MemoryStore() *memory.Store

MemoryStore returns the underlying memory.Store.

func (*Tesseract) RecallMemory

func (c *Tesseract) RecallMemory(ctx context.Context, in memory.RecallInput) ([]memory.RecallResult, error)

RecallMemory retrieves memories by namespace, ranking, and filters.

func (*Tesseract) Search

func (c *Tesseract) Search(ctx context.Context, query string, opts SearchOptions) ([]embedding.SearchResult, error)

Search embeds the query string and returns the top matching records ranked by cosine similarity against all stored embeddings for the configured model.

func (*Tesseract) Store

func (c *Tesseract) Store() *contextstore.Store

Store returns the underlying contextstore.Store.

func (*Tesseract) WriteMemory

func (c *Tesseract) WriteMemory(ctx context.Context, in memory.WriteInput) (memory.Revision, error)

WriteMemory writes a new memory revision.