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 (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)
Constants ¶
This section is empty.
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.
Functions ¶
This section is empty.
Types ¶
type Citation ¶
Citation locates a chunk for an agent: the owning document uri, the heading path, and the 1-based inclusive line range.
type ContextBlock ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
Source Files