memory

Documentation

Overview

Package memory is the verb layer of mnemos: one place that owns the behavior behind every memory operation (search, read, context, list, remember, okfy, forget, move). The CLI commands and the MCP tools are thin adapters over it — they parse arguments or JSON, call a Service method, and format the result — so the two surfaces cannot drift in semantics, gating, or option construction.

A Service is built from the same primitives an *app.App exposes (the open database, the loaded config, the OKF tree root, a secret scanner, and a logger). It deliberately does not build a search retriever: the CLI selects a retriever per command (lexical or hybrid via --semantic) while the MCP server builds one for its lifetime, so the retriever is passed in to Search/Context.

Index

• Variables
• type Citation
• type ContextBlock
• type ForgetResult
• type MoveResult
• type OkfyInput
• type ReadResult
• type RememberInput
• type RememberResult
• type Service
  • func New(db *sql.DB, cfg *config.Config, treeRoot string, ...) *Service
  • func (s *Service) Context(ctx context.Context, r search.Retriever, q search.Query) ([]ContextBlock, error)
  • func (s *Service) Forget(ctx context.Context, path string) (ForgetResult, error)
  • func (s *Service) List(ctx context.Context, opts browse.Options) ([]browse.Entry, error)
  • func (s *Service) Move(ctx context.Context, from, to string) (MoveResult, error)
  • func (s *Service) Okfy(ctx context.Context, in OkfyInput) (ingest.OkfyResult, error)
  • func (s *Service) ReadChunk(ctx context.Context, chunkID string) (ReadResult, error)
  • func (s *Service) ReadDocument(ctx context.Context, uri string) (ReadResult, error)
  • func (s *Service) ReadOne(ctx context.Context, uri, chunkID string) (ReadResult, error)
  • func (s *Service) Remember(ctx context.Context, in RememberInput) (RememberResult, error)
  • func (s *Service) Search(ctx context.Context, r search.Retriever, q search.Query) ([]model.Result, error)

Variables

var (
	ErrAmbiguousRead = errors.New("provide exactly one of uri or chunk_id, not both")
	ErrEmptyRead     = errors.New("provide exactly one of uri or chunk_id")
)

ErrAmbiguousRead and ErrEmptyRead document the two invalid read selectors a surface may pass; surfaces validate their own input shape, but ReadOne lets a surface delegate the choice too.

Types

type Citation

type Citation struct {
	URI         string
	HeadingPath string
	StartLine   int
	EndLine     int
}

Citation locates a chunk for an agent: the owning document uri, the heading path, and the 1-based inclusive line range.

type ContextBlock

type ContextBlock struct {
	Source  string
	Content string
}

ContextBlock is one retrieved passage ready to inject into an LLM prompt: Source cites it as "uri:start-end" and Content is the full chunk text.

type ForgetResult

type ForgetResult struct {
	URI     string
	Deleted bool
}

ForgetResult reports the removed file's uri and whether a file was actually deleted from disk (false when it was already absent — forget is idempotent).

type MoveResult

type MoveResult struct {
	From   string
	To     string
	Result ingest.MoveResult
}

MoveResult reports the old and new uris and the underlying ingest outcome (the re-indexed entries, whether the source was a directory, and any inbound links left dangling).

type OkfyInput

type OkfyInput struct {
	Source     string
	Out        string
	Collection string
	Type       string
	Tags       []string
	Force      bool
}

OkfyInput is a request to convert an existing plain .txt or .md file into an OKF document at Out and index it, leaving the source intact. Source and Out are tree-root-relative paths confined to the tree.

type ReadResult

type ReadResult struct {
	URI        string
	Collection string
	Title      string
	Content    string
	Citation   *Citation
}

ReadResult is the outcome of reading a document or a single chunk. Content is the chunk text or the reconstructed document body; the metadata fields locate it. Citation is set only for a chunk read.

type RememberInput

type RememberInput struct {
	Type       string
	Text       string
	Collection string
	Tags       []string
	Path       string
}

RememberInput is a request to capture a note. Type is a free-form OKF type (e.g. idea, document, Task); Text is the note body; Collection defaults to "default"; Tags are optional frontmatter signals; Path, when set, is a tree-root-relative target ending in .md (else the note is auto-named under the capture directory).

type RememberResult

type RememberResult struct {
	URI        string
	DocumentID string
	Chunks     int
	Type       string
	Deferred   bool
}

RememberResult reports the stored note's tree-relative uri (an immediate citation), the document id, the number of chunks indexed, the recorded type, and whether ingestion was deferred to a watcher (Deferred true means the file is written but not yet indexed, so DocumentID is empty and Chunks is 0).

type Service

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

Service owns the memory verbs over an open store, the loaded configuration, the OKF tree root, and a secret scanner. The same value backs both surfaces.

func New

func New(db *sql.DB, cfg *config.Config, treeRoot string, scanner security.SecretScanner, logger *slog.Logger) *Service

New builds a Service. cfg supplies the write/capture/indexing settings and the gate flags read by the write verbs; treeRoot confines every caller-supplied path; scanner screens captured/converted text for secrets (a nil scanner defaults to a regex scanner so the write verbs are always guarded); logger writes diagnostics. The configured search.default_limit is applied by Search/Context when a caller leaves limit unset.

func (*Service) Context

func (s *Service) Context(ctx context.Context, r search.Retriever, q search.Query) ([]ContextBlock, error)

Context runs q through r and batch-loads each hit's full chunk content, returning LLM-ready blocks in rank order. The retriever only returns a highlighted snippet, so context fetches the whole chunk in one query (avoiding the per-result N+1). A chunk that vanished between search and fetch falls back to its snippet so the block still carries something.

func (*Service) Forget

func (s *Service) Forget(ctx context.Context, path string) (ForgetResult, error)

Forget removes a file from disk and the index. It de-indexes before touching disk (crash-coherent ordering, via ingest.ForgetPath). It is gated by [mcp].allow_delete. Resolve and ForgetPath errors are returned un-prefixed so each surface can add its own ("forget:" / "mcp:").

func (*Service) List

func (s *Service) List(ctx context.Context, opts browse.Options) ([]browse.Entry, error)

List walks the OKF tree on disk and annotates each file with the index metadata mnemos holds, applying opts as filters. It owns the indexed/unindexed mutual-exclusion check (formerly re-implemented on both surfaces) and the include/exclude/security-exclude wiring from config, so both surfaces narrow the tree identically. A nil result is normalized to an empty slice.

func (*Service) Move

func (s *Service) Move(ctx context.Context, from, to string) (MoveResult, error)

Move renames a file or directory within the OKF tree and re-indexes it under the new path, preserving each document's collection. It is gated by [mcp].allow_delete (the old index entries are deleted). The two resolve errors are tagged "source:" / "destination:" so a surface can prefix them ("mv: source:" / "mcp: destination:") and still tell the two apart.

func (*Service) Okfy

func (s *Service) Okfy(ctx context.Context, in OkfyInput) (ingest.OkfyResult, error)

Okfy converts a plain file into an OKF document and indexes it. It is not gated on either surface for the local operator running it directly; the MCP adapter applies the [mcp].allow_write gate at its boundary (the tool is also un-registered when write is off).

func (*Service) ReadChunk

func (s *Service) ReadChunk(ctx context.Context, chunkID string) (ReadResult, error)

ReadChunk returns a single chunk's content and its citation. An unknown chunk_id is a not-found error, not a crash.

func (*Service) ReadDocument

func (s *Service) ReadDocument(ctx context.Context, uri string) (ReadResult, error)

ReadDocument reconstructs a document from its stored chunks ordered by ordinal, de-duplicating the overlapping line ranges the windowed chunker emits. An unknown uri is a not-found error.

func (*Service) ReadOne

func (s *Service) ReadOne(ctx context.Context, uri, chunkID string) (ReadResult, error)

ReadOne dispatches to ReadDocument or ReadChunk based on which of uri/chunkID is set, rejecting the both-set and neither-set cases. It is the single entry the MCP read tool delegates to.

func (*Service) Remember

func (s *Service) Remember(ctx context.Context, in RememberInput) (RememberResult, error)

Remember writes a note as an OKF markdown file and (unless capture is deferred to a watcher) indexes it. It validates the type/text, secret-scans the body before writing anything, confines a caller-chosen path to the tree, and appends a directory log entry. It is gated by [mcp].allow_write.

func (*Service) Search

func (s *Service) Search(ctx context.Context, r search.Retriever, q search.Query) ([]model.Result, error)

Search runs q through r, applying the configured default limit when q.Limit is unset. r is the retriever the surface chose (lexical FTS, or hybrid lexical+vector); the service does not pick one.