tesseract

README

Tesseract by Hollis Labs

Tesseract is a local-first context and memory service for humans, tools, and AI agents. It stores append-only, revisioned records in deterministic namespaces and exposes them over a Go library, CLI, HTTP API, and MCP.

It is designed for workflows where agents need a trustworthy persistence layer before reaching for the filesystem or the web:

• append-only record history with stable heads
• namespace-scoped ownership and token-gated writes
• deterministic views and context packets
• app-to-user promotion workflow instead of silent memory mutation
• optional semantic recall via embeddings

Install

Install the contextd binary with Go:

go install github.com/hollis-labs/tesseract/cmd/contextd@latest

If you are building from source:

git clone https://github.com/hollis-labs/tesseract.git
cd tesseract
go build -o contextd ./cmd/contextd

Use make build only if you want to rebuild the embedded web UI as part of the binary. A normal go install or go build path does not require Node.

Quick Start

1. Inspect the paths Tesseract will use on your machine:

contextd path

1. Create a config file at the reported config-file path. Start from one of:

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

1. Export the provider keys you need:

export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...

Use env.example as a template.

1. Start the daemon:

contextd serve --addr :8089

1. Write and read your first record:

contextd context put \
  --namespace app/demo/session \
  --key goal \
  --actor app:demo \
  --json '{"objective":"ship beta docs"}'

contextd context get --namespace app/demo/session --key goal

Provider Setup

Tesseract currently supports these runtime provider paths:

• Embeddings: openai
• Synthesis: openai, anthropic

Recommended beta setups:

• OpenAI only:
  • embeddings enabled
  • synthesis enabled
• Anthropic + OpenAI:
  • Anthropic for synthesis
  • OpenAI for embeddings
• No provider keys:
  • core context, memory, knowledge, CLI, API, and MCP still work
  • embedding-backed recall and synthesis are unavailable

Example config:

embedding:
  provider: openai
  model: text-embedding-3-large

synthesis:
  provider: anthropic
  model: claude-sonnet-4-5

MCP Setup

Tesseract can run as an MCP stdio server:

contextd mcp --token <capability-token>

Sample Claude Code configuration is in examples/mcp.json.

Typical setup flow:

1. Create a token with the scopes you need.
2. Add a Tesseract entry to your MCP client config.
3. Restart the MCP client.
4. Use context_*, memory_*, and related tools from the client.

Common Commands

contextd serve --addr :8089
contextd path
contextd context put --namespace app/demo/session --key state --actor app:demo --json '{"status":"ok"}'
contextd context get --namespace app/demo/session --key state
contextd context history --namespace app/demo/session --key state
contextd context token create --name demo --scopes write,promote.request --namespaces "app/demo/*"
contextd context packet --namespace "app/demo/*" --budget-items 20 --budget-tokens 4000
contextd backfill-embeddings

Documentation

• docs/README.md for the public docs entrypoint
• docs/QUICKSTART.md for the end-to-end first-run flow
• docs/ARCHITECTURE.md for the core model and invariants
• docs/AGENT-SETUP.md for MCP and Claude Code setup
• docs/MCP_TOOLS.md for the MCP tool catalog
• docs/SPECS/API.md for the HTTP surface
• docs/SPECS/CLI.md for CLI behavior
• CHANGELOG.md for user-visible changes

Build And Test

go test ./...
make build
make smoke

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 = errors.New("embedder unavailable")

ErrEmbedderUnavailable is returned when an embedding operation is attempted but no embedder has been configured on the Tesseract instance.

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/contextd, 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.