Read a memory by ID (e.g. arch-012) or layer-prefixed path (e.g. project:decisions/why-not-rag.md), returning Markdown content, metadata, and supersession links. Unprefixed paths search stores in precedence order. Use gnosys_hybrid_search instead when you do not know the ID, or gnosys_recall for several relevant memories as context.

Save a structured memory without an LLM call, returning its ID, store label, and up to three active overlaps. Supply title, category, tags, and Markdown content; store defaults to project, author to ai, authority to observed, and confidence to 0.8 (also used for an explicit zero). supersedes links comma-separated predecessor IDs; cross-scope or cross-project links require allowCrossScope=true. Use gnosys_update instead to change an existing memory or unlink a predecessor with superseded_by="".

Record usefulness feedback for one memory, returning a signal confirmation. useful increments reinforcement and resets decay; not_relevant records a routing miss without changing the memory; outdated marks it for review. Use gnosys_reflect instead to record an outcome memory, link evidence, and adjust confidence; repeated useful calls reinforce again.

Initialize a project directory, returning its identity, store path, and setup summary. Pass an absolute directory (e.g. /work/app); projectName defaults to its basename. Creates .gnosys/ metadata and registers the project in the central SQLite store; run this before project-scoped operations on a new root. Use gnosys_briefing instead to inspect an already registered project.

Update an existing memory by ID or path, returning a confirmation and changed fields. To archive, retire, or "delete" a memory, set status to archived or superseded with superseded_by (the replacement ID, mapped to supersededBy / --superseded-by in the CLI); hard deletion is human-only by design via the CLI. confidence accepts 0..1; content replaces the Markdown body; supersedes adds predecessor links and superseded_by="" unlinks a predecessor. Links reject cycles and require allowCrossScope=true across scopes or projects. Use gnosys_add_structured instead for a new memory.

Search memories by keyword and meaning, returning ranked snippets, IDs, scores, status, dates, and replacement links. mode is keyword, semantic, or hybrid (default); limit defaults to 15 and activeOnly to false. Use gnosys_recall instead for a context block, or gnosys_read for a full body. Specialist tools require gnosys_toolset {"set":"standard"}: use gnosys_search for plain keyword search, gnosys_federated_search for scope boosts, gnosys_discover for metadata only, or gnosys_semantic_search for embedding-only results. Embedding setup requires gnosys_toolset {"set":"full"} then gnosys_reindex. Example: {"query":"JWT refresh flow","mode":"keyword","limit":5}.

Inspect local memory-system health as JSON with memory counts, maintenance health, graph statistics, and LLM provider status. projectRoot selects the project context; omission uses the detected context. Use gnosys_briefing instead for a project summary and recent activity as Markdown.

Recall relevant memories as a context block for a task, e.g. query="JWT middleware". query="*" selects by reinforcement, confidence, and recency; limit uses config by default and is capped at 15; aggressive defaults to config (true). Use gnosys_hybrid_search instead to inspect ranked results or gnosys_read for one complete body. Registered projectRoot includes project, user, and global memories; omit it for all projects, or run gnosys_init for an unregistered root. Installed hooks may already inject this context per prompt.

Save or replace a user preference across projects, returning its key, title, and value. Use kebab-case keys, e.g. {"key":"code-style","value":"Use named exports"}; title is generated from the key if omitted. Preferences persist as user-scoped memories; the CLI command gnosys sync refreshes generated rules files. Use gnosys_preference_get instead to inspect a key or list preferences.

Read a user preference by key, returning its title, value, confidence, and modified date, or omit key to list all preferences with their keys and values. Keys are kebab-case, e.g. {"key":"code-style"}; missing keys return a not-found message. Use gnosys_preference_set instead to save or replace a preference.

Summarize a project as Markdown with memory counts, categories, activity from the last seven days, top tags, and a summary. projectId takes precedence over projectRoot; otherwise detect from projectRoot or cwd. all=true returns summaries for all projects and ignores both selectors (default false). Use gnosys_dashboard instead for system health, graph statistics, and provider status as JSON.

Record an outcome as a new reflection memory, returning its ID, confidence delta, updated memory IDs and confidences, and relationship count. memoryIds defaults to up to five keyword matches on outcome; success defaults to true and confidenceDelta to +0.05 on success or -0.1 on failure, clamping resulting confidence to 0.05..1. Success also reinforces targets and adds validates links; failure adds contradicts links. Use gnosys_reinforce instead for usefulness feedback without creating an outcome memory; each reflection call creates a new record and applies the delta again.

Traverse stored memory relationships breadth-first, returning an indented text tree of IDs, titles, confidences, depths, and connecting edges. direction is out, in, or both (default); depth defaults to 3 with range 1..10. relTypes accepts stored relationship strings, including references, supersedes, leads_to, follows_from, requires, validates, contradicts, and corroborates; omission follows all types. Example: {"memoryId":"arch-012","depth":2,"relTypes":["requires"]}. To create relationships from source code, use gnosys_trace instead, which requires gnosys_toolset {"set":"standard"}.

List the active tool tier and a catalog of higher-tier tools as text, or set core, standard, or full to switch tiers and return added/removed tool names. Starts on core unless configured otherwise; omit set to inspect without switching. Example: {"set":"standard"} enables specialist search and tracing tools for this session.