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
| Tool | Purpose |
|---|---|
get_context core | The 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 core | Create or update a named, typed thing (Person, Organization, Place, Object, Event) worth referencing again. Takes entity_type, mention and optional fields. |
add_fact core | Record 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 core | Record 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 core | Append 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 core | A session's raw messages, oldest first. Use to review what was said before deciding what is new enough to save. |
Extended profile
| Tool | Purpose |
|---|---|
link_entities | Connect 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_memories | Raw hybrid search over long-term memory: no graph expansion, no session messages. Useful for checking for a near-duplicate before writing. |
get_entity | Full profile of one entity plus its relationships. |
query_graph | Read-only OpenCypher against the graph for anything the other tools can't express. Write clauses (CREATE, MERGE, SET, DELETE) are rejected. |
add_reasoning_trace | Record why a nontrivial decision was made: a goal, an outcome and the memory ids that informed it. |
get_reasoning_traces | Look up past reasoning by goal text, date or a linked entity or fact id. |
export_graph | Dump the entire graph as plain data. Heavy: for bulk inspection or migration, not everyday recall. |
run_lint | Check for structural problems such as unresolved links and schema violations. Diagnostic only. |
delete_memory | Hard-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_extraction | Block 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?"))