liliang-cn/cortexdb/cortexdb-memory-hermes

CortexDB memory for a Python agent (Hermes)

Wire CortexDB in as the memory layer for a Python agent. CortexDB is a pure-Go, single-file database; the Python agent talks to it over gRPC via the cortexdb-client package. Beyond vector/lexical recall, it gives the agent a real knowledge graph (RDF + SPARQL) — the thing most agent-memory layers lack.

When to use this

• The agent should remember user facts/preferences across turns or sessions.
• The agent should recall memories by meaning, not exact match.
• The agent needs entities + relations and multi-hop questions ("who, among the

people Alice knows, works on X").

• You're integrating with Hermes Agent (or any Python agent/framework).

Step 1 — Run the sidecar (once)

CortexDB runs as a local sidecar process, owning one SQLite file.

# install the binary (or download a prebuilt release)
go install github.com/liliang-cn/cortexdb/v2/cmd/cortexdb-grpc@latest
 
# lexical mode — zero config, no API key:
CORTEXDB_PATH=agent.db CORTEXDB_GRPC_TOKEN=s3cret cortexdb-grpc
# → listening on 127.0.0.1:47821

To enable vector/semantic recall, point it at any OpenAI-compatible embeddings endpoint (e.g. a local Ollama):

OPENAI_BASE_URL=http://localhost:11434/v1 \
CORTEXDB_EMBED_MODEL=embeddinggemma CORTEXDB_EMBED_DIM=768 \
CORTEXDB_PATH=agent.db CORTEXDB_GRPC_TOKEN=s3cret cortexdb-grpc

Step 2 — Install the client

pip install cortexdb-client          # or: uv add cortexdb-client

Step 3 — The two core moves: remember + recall

from cortexdb_client import CortexClient, proto
client = CortexClient.connect("127.0.0.1:47821", token="s3cret")
# remember a fact about the user (scoped per user)
client.memory.SaveMemory(proto.SaveMemoryRequest(
    memory_id="pref-coffee",
    user_id="alice", scope="user",
    content="Alice prefers dark roast coffee and dislikes heavy frameworks.",
))
# later turn / next session: recall by meaning
hits = client.memory.SearchMemory(proto.SearchMemoryRequest(
    query="what does the user like to drink?",
    user_id="alice", scope="user", top_k=3,
))
for h in hits.results:
    print(h.memory.content, h.score)

Memory scopes isolate data: scope="user" (per user_id), scope="session" (per session_id), or scope="global". Use user for durable preferences and session for short-lived conversation state.

Step 4 — Knowledge instead of plain memory (RAG)

For documents the agent should retrieve from (not just per-user notes), use the knowledge service — it chunks, indexes, and (with an embedder) does GraphRAG:

client.knowledge.SaveKnowledge(proto.SaveKnowledgeRequest(
    knowledge_id="doc-1",
    title="Project brief",
    content="The user is building an autonomous research agent in Python.",
))
res = client.knowledge.SearchKnowledge(proto.SearchKnowledgeRequest(
    query="what is the user building?", top_k=3,
))

Step 5 — The differentiator: a knowledge graph

Store entities and relations, then traverse them with SPARQL. This is what makes CortexDB more than a vector store for an agent.

iri = lambda v: proto.RdfTerm(kind="iri", value=v)
client.graph.UpsertNamespace(proto.UpsertNamespaceRequest(
    prefix="ex", uri="https://example.com/"))
client.graph.UpsertKnowledgeGraph(proto.UpsertKnowledgeGraphRequest(triples=[
    proto.RdfTriple(subject=iri("ex:alice"), predicate=iri("ex:knows"), object=iri("ex:bob")),
]))
ans = client.graph.QuerySparql(proto.QuerySparqlRequest(
    query="SELECT ?o WHERE { <https://example.com/alice> <https://example.com/knows> ?o . }"))
print(ans.result.count, "result(s)")

Expose CortexDB as Hermes tools

Hermes runs Python and dispatches tools/subagents. Wrap the calls above as small tool functions the agent can call — remember(text), recall(query), relate(from, rel, to), ask_graph(sparql). Each is a 3-line wrapper over the client. A ready-to-import module is provided:

• scripts/memory_tools.py — remember, recall, save_knowledge,

search_knowledge, relate, ask_graph, plus unified recall_context and remember_context, returning plain dicts/strings that drop straight into a tool-calling loop.

For automatic pre-turn recall and completed-turn synchronization, install the native Hermes MemoryProvider at plugins/hermes-cortexdb-memory and set memory.provider: cortexdb. A skill or MCP server exposes tools but does not by itself participate in Hermes' native memory lifecycle.

Install this skill into Hermes

Hermes adopts the agentskills.io standard; skills live under ~/.hermes/skills/ and activate as /skill-name.

# from a URL to this SKILL.md, or a local checkout:
hermes skills install https://raw.githubusercontent.com/liliang-cn/cortexdb/main/skills/cortexdb-memory-hermes/SKILL.md --name cortexdb-memory-hermes
 
# or point Hermes at a directory of skills via ~/.hermes/config.yaml:
#   skills:
#     external_dirs:
#       - /path/to/cortexdb/skills

Then in a Hermes session: /cortexdb-memory-hermes. Hermes also speaks MCP — if you prefer, run cortexdb-mcp-stdio and connect it as an MCP server instead of (or alongside) this skill.

Sub-clients (full surface)

client.knowledge, client.memory, client.graph (RDF/SPARQL/SHACL/inference/ ontology), client.graphrag, client.tools (generic dispatch, same shape as MCP), client.admin. Every RPC takes a proto.<Name>Request and returns the response message. Auth is a bearer token; pass token= to connect.

Notes & gotchas

• Zero-key default: without an embedder the sidecar uses lexical retrieval —

good enough to start, no credentials needed.

• One file, one process: the sidecar owns one SQLite file. Isolate multiple

users via memory scopes (above), not multiple files.

• Plaintext localhost: the bearer token rides plain gRPC; fine on localhost,

add TLS / a reverse proxy for cross-machine use.

• Package and docs: https://pypi.org/project/cortexdb-client/ ·

https://github.com/liliang-cn/cortexdb