Skip to content

database-api.md

Latest commit

 

History

History
111 lines (85 loc) · 4.4 KB

database-api.md

File metadata and controls

111 lines (85 loc) · 4.4 KB

Database API

The application layer should treat these SQL functions as its public contract. Any language can implement an app layer by calling these functions.

Memory Creation

Function Description
create_memory(type, content, importance, trust_level, metadata) Create any memory type
create_episodic_memory(content, importance, trust_level, metadata) Create episodic memory
create_semantic_memory(content, confidence) Create semantic memory
create_procedural_memory(content, steps, prerequisites) Create procedural memory
create_strategic_memory(content, pattern, evidence) Create strategic memory
add_to_working_memory(content, context) Add to working memory buffer

All creation functions generate embeddings via get_embedding() and create graph nodes.

Memory Retrieval

Function Description
fast_recall(query_text, limit) Primary hot-path retrieval (vector + neighborhoods + temporal)
search_similar_memories(query, limit, types) Similarity search with type filter
search_working_memory(query) Search working memory buffer

Heartbeat and Maintenance

Function Description
should_run_heartbeat() Check if heartbeat is due
should_run_maintenance() Check if maintenance is due
run_heartbeat() Open heartbeat, gather context, return external call payloads
execute_heartbeat_actions_batch(heartbeat_id, actions) Apply actions, return outbox payloads
apply_heartbeat_decision(...) Apply a single heartbeat decision
apply_external_call_result(call_payload, output) Feed LLM/embedding results back
complete_heartbeat(...) Finalize state, log heartbeat
run_subconscious_maintenance() Run all maintenance tasks
start_heartbeat() Initialize a new heartbeat

State and Config

Function Description
get_state(key) Get runtime state value
set_state(key, value) Set runtime state value
get_config_text(key) Get config value as text
get_config_int(key) Get config value as integer
get_config_float(key) Get config value as float
get_config_bool(key) Get config value as boolean
set_config(key, value) Set config value

Consent

Function Description
request_consent(...) Returns external call payload for consent request
record_consent(...) Record consent decision

Consent is permanent; refusal is handled by pause/termination, not revocation.

Embeddings

Function Description
get_embedding(text[]) Generate embeddings via HTTP (cached in embedding_cache)
embedding_dimension() Return configured embedding dimension
check_embedding_service_health() Check if embedding service is reachable

Maintenance Functions

Function Description
cleanup_working_memory() Delete expired working memory items
batch_recompute_neighborhoods() Refresh stale precomputed neighbors
cleanup_embedding_cache() Prune old cached embeddings

Graph Operations

Function Description
link_memory_to_concept(memory_id, concept_name) Link memory to concept (creates if needed)
ensure_current_life_chapter() Update narrative life chapter

Character and Identity

Function Description
init_from_character_card(card_json) Initialize identity from character card

Design Principles

  1. DB functions return JSON payloads for external calls -- the app layer executes them
  2. External call results are fed back via apply_external_call_result()
  3. Outbox payloads are published by the app layer (e.g., via RabbitMQ)
  4. The DB does not store queues -- transport logic stays outside
  5. Advisory locks prevent double-execution of maintenance tasks

Related