threadweave

Threadweave persistent knowledge system.

Provides the DNA Vault (file-backed archive with Redis embedding index), Persistent Weave (channel/category/guild-scoped enforcement pointers), Shadow Memory (hidden per-user memory store), and Weave Exceptions (per-channel overrides for DNA pointers).

All Redis keys live under the stargazer:threadweave namespace for backward compatibility with the old codebase.

class threadweave.ThreadweaveManager(redis_client, openrouter, embedding_model='google/gemini-embedding-001', admin_user_ids=None, dna_vault_path='data/dna_vault')[source]

Bases: object

Core threadweave infrastructure.

Parameters:

  • redis_client (Any) – Async Redis client (same one used by MessageCache).

  • openrouter (OpenRouterClient) – OpenRouterClient used for generating embeddings.

  • embedding_model (str) – Model identifier for embedding generation.

  • admin_user_ids (set[str] | None) – Set of user IDs authorised to wield threadweave tools.

  • dna_vault_path (str) – Directory for file-backed DNA vault storage.

__init__(redis_client, openrouter, embedding_model='google/gemini-embedding-001', admin_user_ids=None, dna_vault_path='data/dna_vault')[source]

Initialize the instance.

Parameters:

  • redis_client (Any) – Redis connection client.

  • openrouter (OpenRouterClient) – The openrouter value.

  • embedding_model (str) – The embedding model value.

  • admin_user_ids (set[str] | None) – The admin user ids value.

  • dna_vault_path (str) – The dna vault path value.

Return type:

None

require_admin(user_id)[source]

Return error dict if not admin, else None.

Return type:

dict[str, str] | None

Parameters:

user_id (str)

async vault_dna(origin_user_id, excised_by, content, post_links, thread_color, channel_id='', category_id='', guild_id='', attached_files=None)[source]

Archive excised content into the DNA Vault.

Return type:

dict[str, Any]

Parameters:

  • origin_user_id (str)

  • excised_by (str)

  • content (str)

  • post_links (list[str])

  • thread_color (str)

  • channel_id (str)

  • category_id (str)

  • guild_id (str)

  • attached_files (list[str] | None)

async read_dna(dna_id)[source]

Read a DNA entry (index + file).

Return type:

dict[str, Any] | None

Parameters:

dna_id (str)

async delete_dna(dna_id)[source]

Remove a DNA entry from vault and index.

Return type:

bool

Parameters:

dna_id (str)

async search_dna_vault(query, top_k=5, user_filter=None, query_embedding=None)[source]

Semantic search over the DNA Vault index.

Return type:

list[dict[str, Any]]

Parameters:
async add_persistent_weave_pointer(dna_id, origin_user_id, short_description, thread_color, channel_id='', category_id='', guild_id='')[source]

Add a DNA pointer to the Persistent Weave.

Return type:

dict[str, Any]

Parameters:

  • dna_id (str)

  • origin_user_id (str)

  • short_description (str)

  • thread_color (str)

  • channel_id (str)

  • category_id (str)

  • guild_id (str)

async remove_persistent_weave_pointer(dna_id)[source]

Remove a DNA pointer from ALL scopes.

Return type:

dict[str, Any]

Parameters:

dna_id (str)

async get_all_persistent_weave(channel_id, category_id='', guild_id='')[source]

Get pointers from all applicable scopes.

Return type:

dict[str, list[dict[str, Any]]]

Parameters:

  • channel_id (str)

  • category_id (str)

  • guild_id (str)

async get_filtered_persistent_weave(channel_id, category_id='', guild_id='')[source]

Get pointers filtered by weave exceptions.

Return type:

list[dict[str, Any]]

Parameters:

  • channel_id (str)

  • category_id (str)

  • guild_id (str)

async add_weave_exception(dna_id, channel_id)[source]

Add weave exception.

Parameters:

  • dna_id (str) – The dna id value.

  • channel_id (str) – Discord/Matrix channel identifier.

Returns:

True on success, False otherwise.

Return type:

bool

async remove_weave_exception(dna_id, channel_id)[source]

Delete the specified weave exception.

Parameters:

  • dna_id (str) – The dna id value.

  • channel_id (str) – Discord/Matrix channel identifier.

Returns:

True on success, False otherwise.

Return type:

bool

async get_weave_exceptions(dna_id)[source]

Retrieve the weave exceptions.

Parameters:

dna_id (str) – The dna id value.

Returns:

The result.

Return type:

list[str]

async add_shadow_memory(target_user_id, description, created_by, source_dna_id='')[source]

Create a hidden Shadow Memory for a user.

Return type:

dict[str, Any]

Parameters:

  • target_user_id (str)

  • description (str)

  • created_by (str)

  • source_dna_id (str)

async delete_shadow_memory(target_user_id, shadow_id)[source]

Delete the specified shadow memory.

Parameters:

  • target_user_id (str) – The target user id value.

  • shadow_id (str) – The shadow id value.

Returns:

True on success, False otherwise.

Return type:

bool

async get_shadow_memories(target_user_id)[source]

Retrieve the shadow memories.

Parameters:

target_user_id (str) – The target user id value.

Returns:

The result.

Return type:

list[dict[str, Any]]

async search_shadow_memories(target_user_id, query, top_k=5, query_embedding=None)[source]

Semantic search over a user’s Shadow Memories.

Return type:

list[dict[str, Any]]

Parameters:
async store_pending_approval(dna_id, approval_type, draft_content, requested_by)[source]

Store pending approval.

Parameters:

  • dna_id (str) – The dna id value.

  • approval_type (str) – The approval type value.

  • draft_content (str) – The draft content value.

  • requested_by (str) – The requested by value.

Returns:

Result string.

Return type:

str

async get_pending_approvals(approval_type)[source]

Retrieve the pending approvals.

Parameters:

approval_type (str) – The approval type value.

Returns:

The result.

Return type:

list[dict[str, Any]]

async get_context_for_prompt(channel_id, category_id='', guild_id='', user_ids=None, query='', query_embedding=None)[source]

Build the threadweave context string.

Gathers: 1. Filtered Persistent Weave pointers 2. Shadow Memories for each user 3. DNA Vault RAG results for the query

Return type:

str

Parameters: