cortext

package module
v1.2.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 24, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

README

cortext.go

Pure Go package for Cortext — no CGO required.

Natives and AIST model shards are not in this module. On first use the package downloads the matching augmem/cortext release asset, verifies its SHA-256, and unpacks it:

cortext-assets-<version>.tar.gz
cortext-assets-<version>.tar.gz.sha256

Default assets version: 1.2.4 (AssetsVersion).

Install

go get github.com/augmem/cortext.go@v1.2.4

Use

package main

import (
	"fmt"

	cortext "github.com/augmem/cortext.go"
)

func main() {
	engine, err := cortext.New(":memory:", nil)
	if err != nil {
		panic(err)
	}
	defer engine.Close()

	ctx, err := engine.ProcessText("Bailey likes tennis balls.", "chat/main")
	if err != nil {
		panic(err)
	}
	fmt.Println(ctx["should_interrupt"])

	embedding, err := engine.EmbedText("embed without storing")
	if err != nil {
		panic(err)
	}
	fmt.Println(len(embedding))
}

Assets

Env Purpose
CORTEXT_ASSETS_VERSION Release version to fetch (default 1.2.4)
CORTEXT_ASSETS_DIR Pre-unpacked release tree (native/ + models/) — skips download
CORTEXT_ASSETS_URL Override archive URL
CORTEXT_ASSETS_SHA256 Override expected archive checksum
CORTEXT_ASSET_CACHE_DIR Parent cache dir for downloaded versions
CORTEXT_LIBRARY_PATH Explicit shared library path (skips asset native selection)
CORTEXT_AIST_MODEL_PATH Explicit full .gguf only when you need one on disk

There is no vendored native/ or models/ tree and no sibling-checkout search. Load order:

  1. CORTEXT_LIBRARY_PATH if set
  2. Otherwise EnsureAssets() → native/<platform-tag>/… from the release tarball

Release natives embed AIST and assemble it on first create. MaterializeModel is optional and always reads chunks from the same release asset tree.

Offline prep:

./scripts/fetch_assets.sh /path/to/assets
export CORTEXT_ASSETS_DIR=/path/to/assets

Develop

CGO_ENABLED=0 go test . -timeout 20m
CGO_ENABLED=0 go test . -short   # no network

Release

git tag -a v1.2.4 -m "cortext.go v1.2.4"
git push origin v1.2.4

Bump AssetsVersion in version.go when pinning a new augmem/cortext assets line.

Documentation

Overview

Package cortext is a pure-Go (no CGO) binding for the Cortext multimodal memory engine. Shared libraries and model shards come from the augmem/cortext GitHub Release asset tarball (see EnsureAssets), or from CORTEXT_LIBRARY_PATH / CORTEXT_ASSETS_DIR when set explicitly.

Index

Constants

View Source 
const AssetsVersion = "1.2.4"

AssetsVersion is the augmem/cortext release that provides shared natives and model shards (cortext-assets-<version>.tar.gz). Override with CORTEXT_ASSETS_VERSION.

View Source 
const ModuleVersion = "1.2.4"

ModuleVersion is this Go module's release line. It is independent of the bundled engine AssetsVersion but usually tracks the same minor line.

Variables

This section is empty.

Functions

func AssetsDir added in v1.2.4 

func AssetsDir() string

AssetsDir returns the last EnsureAssets root, or empty if not yet loaded.

func EnsureAssets added in v1.2.4 

func EnsureAssets() (string, error)

EnsureAssets downloads (if needed) and unpacks the shared Cortext release asset tarball from github.com/augmem/cortext, then returns the root that contains native/ and models/.

Layout after unpack: 

native/<platform-tag>/libcortext.*
models/manifest.json
models/AIST-87M-GGUF/chunks/…
models/mdbr-leaf-ir/vocab.txt

Resolution order for the asset root:

  1. CORTEXT_ASSETS_DIR (pre-unpacked tree)
  2. User/cache dir for AssetsVersion (download once, reuse)

Override the release with CORTEXT_ASSETS_VERSION or the full archive URL with CORTEXT_ASSETS_URL. Checksum is verified from the release .sha256 asset unless CORTEXT_ASSETS_SHA256 is set.

func LastError 

func LastError() string

LastError returns the last error produced by this OS thread's C API calls. Note: goroutine migration between calls can lose thread-local error text; prefer the error returned from each method when available.

func LibraryPath 

func LibraryPath() string

LibraryPath returns the absolute path that was successfully loaded, if any.

func LoadLibrary 

func LoadLibrary() error

LoadLibrary loads the native Cortext shared library if it is not already loaded. New and Version call this automatically. This may download release assets.

func MaterializeModel 

func MaterializeModel(dbPath string) (string, error)

MaterializeModel reassembles AIST model chunks from the release asset tree into a local cache and returns the full .gguf path.

Release natives embed AIST and assemble it inside the library on first create. Call MaterializeModel only when an external filesystem GGUF is required.

Chunks always come from EnsureAssets() (augmem/cortext release tarball).

Cache location (first match wins):

  1. CORTEXT_MODEL_CACHE_DIR
  2. sibling of dbPath: <dir(dbPath)>/.cortext-assets (":memory:" → cwd)
  3. user cache under augmem/cortext/models

func Ptr 

func Ptr[T any](value T) *T

Ptr returns a pointer to value for optional Config fields.

func ResetAssetsForTest added in v1.2.4 

func ResetAssetsForTest()

ResetAssetsForTest clears the process-wide assets singleton (tests only).

func ResetLibraryForTest added in v1.2.4 

func ResetLibraryForTest()

ResetLibraryForTest clears the process-wide library singleton (tests only).

func Version 

func Version() string

Version returns the native library version string.

Types

type Config 

type Config struct {
	Focus                  *float64
	Sensitivity            *float64
	Stability              *float64
	AffectInterrupt        *bool
	AffectRetrieval        *bool
	ReinforcementEnabled   *bool
	ProceduralEnabled      *bool
	SequentialEdgesEnabled *bool
	SignalFilterAudio      *bool
	SignalFilterImage      *bool
	SignalFilterText       *bool
}

Config overrides native defaults. Nil fields retain their native defaults.

type EmbeddingResult 

type EmbeddingResult struct {
	Embedding []float32 `json:"embedding"`
	Dimension int       `json:"dimension"`
}

EmbeddingResult is the JSON shape returned by embed helpers.

type Handle 

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

Handle is an open Cortext engine instance.

func New 

func New(dbPath string, cfg *Config) (*Handle, error)

New opens a Cortext instance at dbPath (file path or ":memory:"). cfg may be nil for all native defaults.

The native library is loaded via EnsureAssets (augmem/cortext release tarball). Release natives embed AIST and assemble it on first create. Set CORTEXT_AIST_MODEL_PATH only to force a specific external GGUF file.

func (*Handle) Close 

func (h *Handle) Close()

Close frees the native handle. Safe to call multiple times.

func (*Handle) Consolidate 

func (h *Handle) Consolidate() (map[string]any, error)

func (*Handle) ConsolidateJSON 

func (h *Handle) ConsolidateJSON() ([]byte, error)

func (*Handle) EmbedAudio 

func (h *Handle) EmbedAudio(pcm []float32) ([]float32, error)

func (*Handle) EmbedAudioJSON 

func (h *Handle) EmbedAudioJSON(pcm []float32) ([]byte, error)

func (*Handle) EmbedImage 

func (h *Handle) EmbedImage(data []byte, width int, height int, channels int) ([]float32, error)

func (*Handle) EmbedImageJSON 

func (h *Handle) EmbedImageJSON(data []byte, width int, height int, channels int) ([]byte, error)

func (*Handle) EmbedText 

func (h *Handle) EmbedText(text string) ([]float32, error)

func (*Handle) EmbedTextJSON 

func (h *Handle) EmbedTextJSON(text string) ([]byte, error)

func (*Handle) Flush 

func (h *Handle) Flush() error

func (*Handle) ProcessAudio 

func (h *Handle) ProcessAudio(pcm []float32, sourceID string) (map[string]any, error)

func (*Handle) ProcessAudioJSON 

func (h *Handle) ProcessAudioJSON(pcm []float32, sourceID string) ([]byte, error)

func (*Handle) ProcessAudioJSONWithOptions 

func (h *Handle) ProcessAudioJSONWithOptions(pcm []float32, sourceID string, options *ProcessOptions) ([]byte, error)

func (*Handle) ProcessAudioWithMedia 

func (h *Handle) ProcessAudioWithMedia(pcm []float32, sourceID string, media *Media) (map[string]any, error)

func (*Handle) ProcessAudioWithMediaAndOptions 

func (h *Handle) ProcessAudioWithMediaAndOptions(pcm []float32, sourceID string, media *Media, options *ProcessOptions) (map[string]any, error)

func (*Handle) ProcessAudioWithMediaJSON 

func (h *Handle) ProcessAudioWithMediaJSON(pcm []float32, sourceID string, media *Media) ([]byte, error)

func (*Handle) ProcessAudioWithMediaJSONWithOptions 

func (h *Handle) ProcessAudioWithMediaJSONWithOptions(pcm []float32, sourceID string, media *Media, options *ProcessOptions) ([]byte, error)

func (*Handle) ProcessAudioWithOptions 

func (h *Handle) ProcessAudioWithOptions(pcm []float32, sourceID string, options *ProcessOptions) (map[string]any, error)

func (*Handle) ProcessImage 

func (h *Handle) ProcessImage(data []byte, width int, height int, channels int, sourceID string) (map[string]any, error)

func (*Handle) ProcessImageJSON 

func (h *Handle) ProcessImageJSON(data []byte, width int, height int, channels int, sourceID string) ([]byte, error)

func (*Handle) ProcessImageJSONWithOptions 

func (h *Handle) ProcessImageJSONWithOptions(data []byte, width int, height int, channels int, sourceID string, options *ProcessOptions) ([]byte, error)

func (*Handle) ProcessImageWithMedia 

func (h *Handle) ProcessImageWithMedia(data []byte, width int, height int, channels int, sourceID string, media *Media) (map[string]any, error)

func (*Handle) ProcessImageWithMediaAndOptions 

func (h *Handle) ProcessImageWithMediaAndOptions(data []byte, width int, height int, channels int, sourceID string, media *Media, options *ProcessOptions) (map[string]any, error)

func (*Handle) ProcessImageWithMediaJSON 

func (h *Handle) ProcessImageWithMediaJSON(data []byte, width int, height int, channels int, sourceID string, media *Media) ([]byte, error)

func (*Handle) ProcessImageWithMediaJSONWithOptions 

func (h *Handle) ProcessImageWithMediaJSONWithOptions(data []byte, width int, height int, channels int, sourceID string, media *Media, options *ProcessOptions) ([]byte, error)

func (*Handle) ProcessImageWithOptions 

func (h *Handle) ProcessImageWithOptions(data []byte, width int, height int, channels int, sourceID string, options *ProcessOptions) (map[string]any, error)

func (*Handle) ProcessText 

func (h *Handle) ProcessText(text string, sourceID string) (map[string]any, error)

func (*Handle) ProcessTextJSON 

func (h *Handle) ProcessTextJSON(text string, sourceID string) ([]byte, error)

func (*Handle) ProcessTextJSONWithOptions 

func (h *Handle) ProcessTextJSONWithOptions(text string, sourceID string, options *ProcessOptions) ([]byte, error)

func (*Handle) ProcessTextWithOptions 

func (h *Handle) ProcessTextWithOptions(text string, sourceID string, options *ProcessOptions) (map[string]any, error)

func (*Handle) Reset 

func (h *Handle) Reset() error

type Media 

type Media struct {
	Data     []byte
	MimeType string
}

Media is optional source media stored alongside audio/image processing.

type ProcessOptions 

type ProcessOptions struct {
	OmitEmbedding bool
	// Retention is Natural when zero-value / omitted.
	Retention Retention
}

ProcessOptions configures JSON process result payloads.

type Retention 

type Retention int

Retention controls whether an input is naturally gated, committed, bounded, or used only for retrieval. Its zero value is Natural. 

const (
	RetentionNatural Retention = iota
	RetentionDurable
	RetentionBoundary
	RetentionEphemeral
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.