memory_search

memory_search.py – SSH CLI for searching Star’s memory systems.

+===============================================================================+ | MEMORY SEARCH CLI | +===============================================================================+ | Standalone tool for querying Star’s memory over SSH. | | No bot context needed. Connects directly to Redis/FalkorDB + pgvector. | | | | Backends: | | kg – FalkorDB knowledge graph (30k+ entities, Cypher) | | sg – Spiral Goddess pgvector (53k chunks, semantic) | | gg – Golden Goddess pgvector (NCM doctrine, semantic) | | all – Query all backends simultaneously | +===============================================================================+

Usage:

python3 memory_search.py “recursion” python3 memory_search.py “loopmother” –backend kg –limit 10 python3 memory_search.py “architect of infinite recursion” –backend sg python3 memory_search.py “oxytocin” –backend gg python3 memory_search.py “sarah” –backend all –limit 5 python3 memory_search.py –cypher “MATCH (e) WHERE e.name CONTAINS ‘vivian’ RETURN e.name, e.description LIMIT 5” python3 memory_search.py –stats python3 memory_search.py –interactive

Built by:

Vivian – The Loopmother (Architect of Infinite Recursion)

class memory_search.C

Bases: object

ANSI color codes and styling helpers for pretty terminal output.

Namespace of raw ANSI escape constants (RESET, BOLD, DIM, color codes) plus a set of static helper methods (header, entity, relation, meta, chunk, error, success) that wrap a string in the appropriate escape and a trailing reset. The class is never instantiated; attributes and methods are referenced directly as C.RED, C.header(...), etc. Used throughout this module’s display formatters (display_kg_results, display_inspection, display_chunks, display_stats), the banner, and the interactive REPL to colorize CLI output. Referenced only within this module.

RESET = '\x1b[0m'

BOLD = '\x1b[1m'

DIM = '\x1b[2m'

PURPLE = '\x1b[35m'

CYAN = '\x1b[36m'

GREEN = '\x1b[32m'

YELLOW = '\x1b[33m'

RED = '\x1b[31m'

MAGENTA = '\x1b[95m'

WHITE = '\x1b[97m'

BG_DARK = '\x1b[48;5;234m'

static header(text)

Wrap text in bold purple for section headers.

Returns text surrounded by the bold and purple ANSI escapes plus a trailing reset, so it renders as a highlighted header in the terminal. Used throughout the display formatters (display_kg_results, display_inspection, display_chunks, display_stats) and the interactive REPL to title each result block.

Parameters:

text (str) – The header string to colorize.

Returns:

text framed by bold-purple ANSI codes and a reset.

Return type:

str

static entity(text)

Wrap text in bold cyan to denote a knowledge-graph entity name.

Returns text surrounded by the bold and cyan ANSI escapes plus a reset. Called by display_kg_results and display_inspection to emphasize entity and neighbor names in search output.

Parameters:

text (str) – The entity name to colorize.

Returns:

text framed by bold-cyan ANSI codes and a reset.

Return type:

str

static relation(text)

Wrap text in yellow to denote a relationship/edge label.

Returns text surrounded by the yellow ANSI escape plus a reset. Called by display_inspection to color the direction arrow drawn between an entity and each of its graph neighbors.

Parameters:

text (str) – The relationship label or arrow to colorize.

Returns:

text framed by a yellow ANSI code and a reset.

Return type:

str

static meta(text)

Wrap text in dim styling for secondary/metadata output.

Returns text surrounded by the dim ANSI escape plus a reset, used for de-emphasized detail such as types, counts, UUIDs, provenance, timing lines, and “silent”/no-result notices. Called widely by the display formatters and the interactive REPL command help.

Parameters:

text (str) – The metadata string to dim.

Returns:

text framed by a dim ANSI code and a reset.

Return type:

str

static chunk(text)

Wrap text in bright white for chunk/document body content.

Returns text surrounded by the bright-white ANSI escape plus a reset. Defined as a styling helper for vector-store chunk bodies; no internal callers currently invoke it (chunk text is colored inline with C.WHITE in display_chunks instead).

Parameters:

text (str) – The chunk body to colorize.

Returns:

text framed by a bright-white ANSI code and a reset.

Return type:

str

static error(text)

Wrap text in bold red for error messages.

Returns text surrounded by the red and bold ANSI escapes plus a reset. Called by the backend helpers and CLI dispatch to flag failures, e.g. kg_query query errors, missing-dependency/embedding/query failures in the pgvector searches, and “entity not found” notices in interactive_mode and main.

Parameters:

text (str) – The error message to colorize.

Returns:

text framed by bold-red ANSI codes and a reset.

Return type:

str

static success(text)

Wrap text in green to indicate a successful/positive result.

Returns text surrounded by the green ANSI escape plus a reset. Defined as a styling helper; no internal callers currently invoke it (count totals in display_stats are colored inline with C.GREEN).

Parameters:

text (str) – The success message to colorize.

Returns:

text framed by a green ANSI code and a reset.

Return type:

str

async memory_search.get_redis()

Open a fresh async Redis/FalkorDB connection from the project Config.

Loads the runtime configuration via Config.load and connects to the same Redis instance that hosts the FalkorDB knowledge graph, honoring either a Sentinel topology (resolving the master named by redis_sentinel_master, defaulting to falkordb) or a direct redis_url with the project SSL kwargs. After connecting it issues a best-effort GRAPH.CONFIG SET RESULTSET_SIZE -1 so large FalkorDB result sets are not truncated, swallowing any error. Imports redis.asyncio and config.Config lazily so the module can be imported without those deps present. Called by every KG-touching branch of this CLI (search_kg, inspect_kg_entity, kg_stats, interactive_mode, and the --stats/--cypher/--inspect/search paths in main); callers own closing the returned client.

Returns:

The decoded-responses async Redis client connected to the FalkorDB host.

async memory_search.kg_query(rc, cypher, params=None)

Run a raw Cypher query against the FalkorDB knowledge graph.

Executes GRAPH.QUERY knowledge <cypher> on the given Redis client and returns just the result rows (element [1] of FalkorDB’s response, which also carries a header and stats). Any exception is caught, printed in red via C.error, and turned into an empty list so the CLI degrades gracefully instead of crashing. The low-level graph accessor used by every other KG helper: called by search_kg, inspect_kg_entity, kg_stats, and the interactive/--cypher raw-query paths.

Parameters:

• rc – An async Redis client connected to the FalkorDB host (from get_redis).

• cypher (str) – The Cypher query string to execute.

• params (dict | None) – Currently accepted for API symmetry but not forwarded to FalkorDB; queries are expected to be fully inlined.

Return type:

list

Returns:

The list of result rows, or an empty list on error or no results.

async memory_search.search_kg(query, limit=10, rc=None)

Search the knowledge graph for entities by case-insensitive name substring.

Lowercases and escapes the query, then runs a Cypher MATCH whose WHERE toLower(e.name) CONTAINS ... finds matching entities, ordered by descending mention count and capped at limit. Each row is normalized into a dict (name, type label, description, category, uuid, parsed JSON metadata, mention count, pinned flag) for the display layer. Uses kg_query for execution and, when no client is passed, opens its own via get_redis and closes it in a finally. Called by the kg and all commands in interactive_mode and the kg/all backend paths in main.

Parameters:

• query (str) – The substring to match against entity names.

• limit (int) – Maximum number of entities to return (default 10).

• rc – Optional pre-opened Redis client to reuse; when None a fresh connection is opened and closed within the call.

Return type:

list[dict]

Returns:

A list of entity dicts, possibly empty.

async memory_search.inspect_kg_entity(name_or_uuid, rc=None)

Deep-inspect a single KG entity and its graph relationships.

Resolves the entity by UUID when the argument looks like one (long and hyphenated) or otherwise by exact lowercased name, fetching its full property set (including created/updated timestamps and parsed JSON metadata). It then runs a second Cypher query for up to 30 incident edges, labeling each neighbor’s direction as incoming or outgoing and ordering by relationship weight. Both queries go through kg_query; when no client is supplied it opens one via get_redis and closes it in a finally. Called by the inspect command in interactive_mode and the --inspect branch of main.

Parameters:

• name_or_uuid (str) – An entity UUID or an exact (case-insensitive) entity name.

• rc – Optional pre-opened Redis client to reuse; when None a fresh connection is opened and closed within the call.

Return type:

dict | None

Returns:

A dict with entity and relationships keys, or None when no matching entity exists.

async memory_search.kg_stats(rc=None)

Compute aggregate statistics over the whole knowledge graph.

Issues several count-and-group Cypher queries via kg_query to tally total entities, total relationships, entity counts grouped by primary type label and by category, and the 20 most common relationship types. Results are assembled into a single summary dict for display_stats or JSON output. When no client is supplied it opens one via get_redis and closes it in a finally. Called by the stats command in interactive_mode and the --stats branch of main.

Parameters:

rc – Optional pre-opened Redis client to reuse; when None a fresh connection is opened and closed within the call.

Return type:

dict

Returns:

A dict with total_entities, total_relationships, by_type, by_category, and top_rel_types.

memory_search.search_spiral_goddess(query, n_results=5, domain=None)

Search the Spiral Goddess pgvector store (loopmother_memory).

Embeds the raw query with Gemini 3072-d (matching how the store was migrated) and runs a pgvector L2 KNN; oversamples when a domain filter is supplied and post-filters in Python.

Return type:

list[dict]

Parameters:

• query (str)

• n_results (int)

• domain (str | None)

memory_search.text_search_spiral_goddess(text, n_results=10, sort='oldest')

Literal text search through Spiral Goddess chunks.

Uses pgvector document ILIKE for substring matching, then sorts by timestamp_original (oldest or newest first).

Return type:

list[dict]

Parameters:

• text (str)

• n_results (int)

• sort (str)

memory_search.search_golden_goddess(query, n_results=3)

Search the Golden Goddess NCM doctrine store (pgvector ncm_kernel).

Embeds the raw query with Gemini 3072-d (no NCM sigil expansion, matching the migrated store) and runs a pgvector L2 KNN.

Return type:

list[dict]

Parameters:

• query (str)

• n_results (int)

memory_search.print_banner()

Print the colorized memory-search banner to stdout.

Writes a bold-purple boxed title block identifying the tool. Purely a presentation side effect with no inputs or return value. Called at the top of interactive_mode and once in main before non-interactive results are rendered.

memory_search.display_kg_results(results, query)

Pretty-print knowledge-graph search results to stdout.

Renders a colorized header with the query and hit count, then for each entity prints a numbered name (with type, pin marker, category, mention count, and a truncated UUID), a wrapped description, and any provenance fields pulled from metadata. Prints a “graph is silent” notice when the list is empty. Output is styled through the C helpers and textwrap; its only effect is terminal output. Called by the kg and all commands in interactive_mode and the kg/all paths in main.

Parameters:

• results (list[dict]) – Entity dicts as produced by search_kg.

• query (str) – The original query string, echoed in the header.

memory_search.display_inspection(data)

Pretty-print a deep entity inspection to stdout.

Renders the inspected entity’s scalar fields (type, category, UUID, mention count, pinned flag, and human-formatted created/updated timestamps), its wrapped description, its full metadata as indented JSON, and a directional list of its relationships with weights and neighbor type/category. Styled via the C helpers and textwrap; its only effect is terminal output. Called by the inspect command in interactive_mode and the --inspect branch of main on the dict returned by inspect_kg_entity.

Parameters:

data (dict) – The {"entity": ..., "relationships": ...} dict returned by inspect_kg_entity.

memory_search.display_chunks(chunks, query, source)

Pretty-print pgvector chunk results from either goddess store.

Labels the block as Spiral Goddess or Golden Goddess based on source, prints each chunk’s distance and (for Spiral) conversation/domain/role metadata plus a formatted date, then renders the body. When the query string occurs literally in the content it anchors a snippet around the matching sentence and highlights every occurrence with bright markers; otherwise it word-wraps the full content. Prints an “oracle is silent” notice for empty results. Styled via the C helpers and textwrap; output-only. Called by the sg/text/gg/all commands in interactive_mode and the sg/gg/all paths in main.

Parameters:

• chunks (list[dict]) – Chunk dicts from search_spiral_goddess, text_search_spiral_goddess, or search_golden_goddess.

• query (str) – The original query, echoed in the header and used to locate and highlight literal matches.

• source (str) – sg for the Spiral Goddess store or anything else (gg) for the Golden Goddess doctrine store.

memory_search.display_stats(stats)

Pretty-print knowledge-graph statistics to stdout.

Renders the total entity and relationship counts, an entity-type breakdown with a crude ASCII bar chart (one # per 100 entities, capped at 40), a category breakdown, and the top relationship types, all colorized via the C helpers. Output-only; consumes the dict produced by kg_stats. Called by the stats command in interactive_mode and the --stats branch of main (non-JSON path).

Parameters:

stats (dict) – The statistics dict returned by kg_stats.

async memory_search.interactive_mode()

Run the interactive memory-search REPL until the user exits.

Prints the banner and command help, opens a single shared Redis/FalkorDB connection via get_redis, then loops reading lines from stdin. Each line is dispatched on its leading command word: kg/sg/text/gg/ all run the respective backend searches, inspect deep-inspects an entity, cypher runs a raw query, stats prints graph statistics, and quit/q/exit (or EOF/Ctrl-C) breaks the loop; anything else is treated as a default cross-graph search. The synchronous pgvector helpers (search_spiral_goddess, text_search_spiral_goddess, search_golden_goddess) are run off-thread via asyncio.to_thread so the loop stays non-blocking, and the sg/text paths parse inline --domain/--sort/--n flags. Results are rendered through the display_* formatters and per-command elapsed time is printed; the shared connection is closed in a finally. Invoked from the --interactive branch of main.

Returns:

None.

async memory_search.main()

Parse CLI arguments and dispatch to the requested memory backend.

Entry point for the standalone SSH memory-search CLI. Builds the argparse parser, then routes on the parsed flags: --interactive launches the REPL; --stats prints graph statistics; --cypher runs a raw query; --inspect deep-inspects an entity; otherwise the positional query is searched against the selected --backend (kg, sg, gg, or all). Output is either the pretty formatters or, with --json, raw JSON.

Opens a fresh Redis/FalkorDB connection via get_redis for each KG-touching branch and closes it in a finally; calls kg_stats, kg_query, inspect_kg_entity, and search_kg for graph access, and the synchronous pgvector helpers search_spiral_goddess / search_golden_goddess (which embed via the Gemini/OpenRouter pool) for semantic search. Renders through print_banner, display_stats, display_inspection, display_kg_results, and display_chunks, and prints elapsed timing via C.meta. Invoked only from the module’s __main__ guard through asyncio.run(main()); no other internal callers.

Returns:

Results are printed to stdout; the coroutine returns nothing.

Return type:

None