Tools reference

The server exposes two profiles. Core is six tools, enough for most agents. Extended adds ten more. Choose with --profile core|extended.

The server also sends the agent usage instructions when it connects: write proactively, prefer links over loose strings, and call get_context before answering anything that depends on prior memory.

Core profile

ToolPurpose
get_context coreThe main recall call. Hybrid search over long-term memory, one hop of graph expansion from each hit, and recent session messages, assembled into one token-budgeted block. Arguments: query, optional session_id, token_budget (default 2000), top_k (default 8).
add_entity coreCreate or update a named, typed thing (Person, Organization, Place, Object, Event) worth referencing again. Takes entity_type, mention and optional fields.
add_fact coreRecord a subject-predicate-object statement, with optional confidence and an about link. The least structured write; if both sides are named things, prefer two entities plus link_entities.
record_preference coreRecord a user's stated like, want or opinion as its own node. Prioritised in get_context over a generic fact saying the same thing. Optional about link to an entity.
add_message coreAppend a raw message to a session's short-term history. It doesn't make content searchable as long-term memory by itself; extract knowledge with the other write tools too.
get_history coreA session's raw messages, oldest first. Use to review what was said before deciding what is new enough to save.

Extended profile

ToolPurpose
link_entitiesConnect two existing entities with a typed relationship (for example a Person works_at an Organization). This is what turns separate writes into a graph. Call it whenever you write two related entities.
search_memoriesRaw hybrid search over long-term memory: no graph expansion, no session messages. Useful for checking for a near-duplicate before writing.
get_entityFull profile of one entity plus its relationships.
query_graphRead-only OpenCypher against the graph for anything the other tools can't express. Write clauses (CREATE, MERGE, SET, DELETE) are rejected.
add_reasoning_traceRecord why a nontrivial decision was made: a goal, an outcome and the memory ids that informed it.
get_reasoning_tracesLook up past reasoning by goal text, date or a linked entity or fact id.
export_graphDump the entire graph as plain data. Heavy: for bulk inspection or migration, not everyday recall.
run_lintCheck for structural problems such as unresolved links and schema violations. Diagnostic only.
delete_memoryHard-delete an entity. Fails if it still has links unless detach=true, which removes them too. For correcting a mistaken write, not routine cleanup.
wait_for_extractionBlock until the background extraction pass triggered by add_message finishes. Only relevant when auto-extract is on and the agent is not writing memories itself.

Calling the tools from Python

The tools are plain methods on ToolServer, with no MCP dependency, so you can use them directly or in tests.

# pip install kgl-memory   (the [mcp] extra is only needed to run the server)
from kgl_memory.tools import ToolServer

ts = ToolServer("memory/graph", auto_extract=False)
ts.add_entity("Object", "billing-service", {"kind": "service"})
ts.add_fact("billing-service", "uses_database", "PostgreSQL 16")
print(ts.get_context("which database does billing use?"))