Documentation
¶
Overview ¶
Package engine is the implementation behind github.com/Coder8124/logos.
The root of this module is the published import path and carries the API documentation; the code lives here, one directory down, so the repository root stays readable. That the root is a thin facade of aliases is the only reason this split is possible at all: Go binds an import path to a directory, so moving these files without leaving something behind would have changed the import every embedder already wrote.
The exported surface is split across files by the question a caller is asking: context.go (what do I need to start), continuity.go (record where I stopped), deadend.go (has this been ruled out), memory.go (what's known about the user), vault.go (search the notes), serve.go (put a host in front of it). This file holds the domain types, and opening and closing a vault.
Index ¶
- Constants
- func Explain(approach string, rulings []Ruling) string
- type Checkpoint
- type Context
- type Hit
- type Kind
- type Logos
- func (b *Logos) Ask(question string, k int) (string, []Hit, error)
- func (b *Logos) Checkpoint(c Checkpoint) (string, error)
- func (b *Logos) Close() error
- func (b *Logos) Context(req Request) (*Context, error)
- func (b *Logos) Embedded() bool
- func (b *Logos) Forget(id int64) error
- func (b *Logos) History(project string, n int) ([]Checkpoint, error)
- func (b *Logos) Index() (SyncReport, error)
- func (b *Logos) Memories() ([]Memory, error)
- func (b *Logos) Note(project, text string) error
- func (b *Logos) Notes(project string) ([]Note, error)
- func (b *Logos) Projects() ([]string, error)
- func (b *Logos) Recall(query string, k int) ([]Memory, error)
- func (b *Logos) Remember(text string, kind Kind) (Receipt, error)
- func (b *Logos) Resume(project string) (*Context, error)
- func (b *Logos) Search(query string, k int) ([]Hit, error)
- func (b *Logos) ServeMCP(in io.Reader, out io.Writer) error
- func (b *Logos) Tried(approach, project string) ([]Ruling, error)
- func (b *Logos) Vault() string
- func (b *Logos) Why(file string, limit int) ([]Mention, error)
- type Memory
- type Mention
- type Note
- type Option
- type Receipt
- type Request
- type Ruling
- type SyncReport
Constants ¶
const ( Preference = memory.Preference Person = memory.Person Fact = memory.Fact Standing = memory.Context Procedure = memory.Procedure )
Memory kinds, re-exported so callers need not reach into internal packages.
Variables ¶
This section is empty.
Functions ¶
func Explain ¶
Explain renders the result of Tried as prose to put in front of a model, taking the same approach string so the output can quote what was proposed. A recorded failure is evidence, not a veto, and the wording says so. An empty slice renders as an explicit "no record", which is worth showing: silence and approval are different answers.
Types ¶
type Checkpoint ¶
type Checkpoint = session.Checkpoint
Checkpoint is where an agent stopped, written well enough that a different agent can start. Failed is the field that earns its keep.
type Context ¶
type Context = contextpack.Pack
Context is everything bearing on a task, budgeted. Call Render for the markdown to put in a model's context window.
type Logos ¶
type Logos struct {
// contains filtered or unexported fields
}
Logos is an open vault. It is safe to keep for the life of a process and must be closed when done. Not safe for concurrent use across goroutines: the underlying SQLite handle is single-writer by design.
func Open ¶
Open loads the vault at path, creating its cache if absent.
The vault directory itself must exist; logos will not invent one, because pointing this at a typo and silently creating an empty knowledge base is a worse failure than an error.
func (*Logos) Ask ¶
Ask retrieves and then answers in prose, citing what it used. Requires a chat model; without one it returns an error rather than a guess.
func (*Logos) Checkpoint ¶
func (b *Logos) Checkpoint(c Checkpoint) (string, error)
Checkpoint commits where you stopped to a markdown note in the vault and returns its slug.
Call it before finishing a session, not after. Anything omitted is lost, and the field that matters most is Failed: approaches that did not work are the expensive knowledge, and without them the next agent repeats them.
func (*Logos) Context ¶
Context assembles everything bearing on a task: where the last agent stopped, what it ruled out, uncommitted progress since, the project dossier, the prose of relevant notes, notes reached one hop through the user's own links, memories with their provenance, and open commitments — spent against a token budget and cited by source.
This is the call to make at the start of a task, in preference to Recall. Recall answers "what do you know about X"; this answers "give me what I need to do X", which is not a longer version of the same question.
func (*Logos) Embedded ¶
Embedded reports whether a model runtime was found. When false, retrieval is lexical and graph-only — still useful, measurably weaker.
func (*Logos) History ¶
func (b *Logos) History(project string, n int) ([]Checkpoint, error)
History returns a project's checkpoints, newest first.
func (*Logos) Index ¶
func (b *Logos) Index() (SyncReport, error)
Index reconciles the vault into the cache: notes, embeddings and memories. Call it after writing files into the vault by other means, or on a watcher.
func (*Logos) Note ¶
Note records one line of progress. Cheap and meant to be called often — after a decision, a dead end, a surprising discovery. Notes stay uncommitted until Checkpoint folds them into a durable record, so use them freely rather than saving everything for the end.
func (*Logos) Notes ¶
Notes returns a project's uncommitted progress — work that happened but was never written down properly, including anything left by an agent that died mid-task.
func (*Logos) Projects ¶
Projects lists every scope that has at least one checkpoint, worktree scopes included — each one spelled the way History takes it back.
func (*Logos) Remember ¶
Remember stores something durable about the user and reports what happened: whether it created a fact or corroborated one already held. Near-identical statements reinforce rather than duplicate.
func (*Logos) Resume ¶
Resume picks up a project where the last agent left off. Equivalent to Context with a continuation task, and named separately because that is how people think about it.
func (*Logos) ServeMCP ¶
ServeMCP speaks the Model Context Protocol over the given streams, exposing this vault's tools to any MCP host. Use it to put your own product in front of logos's memory rather than reimplementing the tool surface.
A missing model runtime is not an error, matching Open: retrieval degrades to lexical and every continuity tool works untouched. Refusing to serve would have contradicted the rest of this API, which is built to keep working on a machine with no models on it.
It blocks until the input stream closes.
func (*Logos) Tried ¶
Tried reports whether an approach has already been ruled out, searching every dead end recorded across the whole vault — other projects included, and findings left in working notes by agents that no longer exist.
Call this before proposing a solution, especially when it seems obvious: obvious approaches are the ones already attempted. Pass the project being worked on so rulings from elsewhere can be flagged as possibly not transferring. An empty result means no record, which is not the same as approval.
func (*Logos) Why ¶
Why reports what was being decided when a file was worked on: the decisions taken and the approaches ruled out while it was being touched, newest first.
The complement to `git blame`, which answers who and when and cannot answer why. Matching on the path is deliberately loose — an agent records whatever path it had in hand and a caller asks with whatever they have — so a bare filename or a partial path both resolve.
It reads markdown from the vault, so it needs no model and no index. limit of 0 means every match.
type Mention ¶
Mention is a checkpoint that touched a file, and what was being worked out at the time. Returned by Why.
type Option ¶
type Option func(*config)
An Option configures Open.
func WithAgent ¶
WithAgent sets the name recorded against notes and checkpoints — "claude", "cursor", your own product's name. A handoff is meaningless without knowing who is handing off, so this is worth setting.
func WithEmbeddingModel ¶
WithEmbeddingModel names the embedding model instead of taking the detected default.
func WithoutEmbedding ¶
func WithoutEmbedding() Option
WithoutEmbedding skips model discovery. Retrieval then uses lexical search and graph traversal only — no model process required, which is what you want in tests and CI.
type Receipt ¶
Receipt reports what a write actually did — created a fact, or corroborated one already held.
type Request ¶
type Request struct {
// Task is what you are about to do, in a sentence. Required.
Task string
// Project narrows to one piece of work. Optional — when empty, the task
// text is matched against known projects.
Project string
// Budget is the approximate token ceiling. Zero means 4000.
Budget int
}
A Request describes what you are about to do. Task is the important field: "continue the MCP implementation" retrieves differently from a project name alone, because it says which corner of the project matters right now.
Source Files