cortexdb-memory-hermes
/cortexdb-memory-hermes
Give a Python agent (such as Hermes Agent by Nous Research) durable, local-first memory plus a queryable SPARQL knowledge graph, backed by CortexDB through its gRPC sidecar and the cortexdb-client PyPI package. Use when a Python agent needs to remember facts about a user across turns/sessions, recall them by meaning, store entities and relations, or answer multi-hop questions — and when the user mentions CortexDB, agent memory, long-term memory, RAG, knowledge graph, Hermes, or "remember this".
- Author
- liliang-cn ↗
- Repository
- cortexdb ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 7
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/memory_tools.py
What it does and when to use it
Give a Python agent (such as Hermes Agent by Nous Research) durable, local-first memory plus a queryable SPARQL knowledge graph, backed by CortexDB through its gRPC sidecar and the cortexdb-client PyPI package. Use when a Python agent needs to remember facts about a user across turns/sessions, recall them by meaning, store entities and relations, or answer multi-hop questions — and when the user mentions CortexDB, agent memory, long-term memory, RAG, knowledge graph, Hermes, or "remember this".
Triggers from the description
Original author description
Give a Python agent (such as Hermes Agent by Nous Research) durable, local-first memory plus a queryable SPARQL knowledge graph, backed by CortexDB through its gRPC sidecar and the cortexdb-client PyPI package. Use when a Python agent needs to remember facts about a user across turns/sessions, recall them by meaning, store entities and relations, or answer multi-hop questions — and when the user mentions CortexDB, agent memory, long-term memory, RAG, knowledge graph, Hermes, or "remember this".
How it works
- When to use this
- Step 1 — Run the sidecar (once)
- Step 2 — Install the client
- Step 3 — The two core moves: remember + recall
- Step 4 — Knowledge instead of plain memory (RAG)
- Step 5 — The differentiator: a knowledge graph
- Expose CortexDB as Hermes tools
- Install this skill into Hermes
- Sub-clients (full surface)
- Notes & gotchas
SKILL.md preview
---
name: cortexdb-memory-hermes
description: Give a Python agent (such as Hermes Agent by Nous Research) durable, local-first memory plus a queryable SPARQL knowledge graph, backed by CortexDB through its gRPC sidecar and the cortexdb-client PyPI package. Use when a Python agent needs to remember facts about a user across turns/sessions, recall them by meaning, store entities and relations, or answer multi-hop questions — and when the user mentions CortexDB, agent memory, long-term memory, RAG, knowledge graph, Hermes, or "remember this".
license: MIT
compatibility: Requires Python 3.9+, pip, and the cortexdb-grpc sidecar binary (Go install or prebuilt release). Optional embeddings via any OpenAI-compatible endpoint (e.g. Ollama).
metadata: {"author": "liliang-cn", "project": "cortexdb", "version": "1.0"}
---
# 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.
```bash
# 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):
```bash
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
```bash
pip install cortexdb-client # or: uv add cortexdb-client
```
## Step 3 — The two core moves: remember + recall
```python
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:
```python
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.
```python
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`.
```bash
# 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
Files in this package (2)
- SKILL.md 7 KB
- scripts/memory_tools.py 6 KB
Versions
The database has no other skills named cortexdb-memory-hermes.
Database snapshot: 13.11.2026 · package version f26ac621c354 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100cortexdb-memory-openclaw
Give a Node.js agent (such as OpenClaw) durable, local-first memory plus a queryable SPARQL knowledge graph, backed by CortexDB through its gRPC sidecar and the cortexdb-client npm package. Use when a Node agent needs to remember facts about a user across turns/sessions, recall… - 100cortexdb
Use CortexDB for local-first AI memory, vector search, RAG, knowledge graphs, SPARQL/RDFS/SHACL, corpus-to-graph workflows, and MCP/tool calling. Use when working with CortexDB, embeddings, memory, RAG, GraphRAG, knowledge graph, RDF, SPARQL, SHACL, memoryflow, graphflow, or MCP tools. - 100agent-memory
Give an agent persistent semantic memory with @three-ws/agent-memory. Use when code needs to remember facts across sessions, recall them by meaning, read the entity graph, or curate an agent's working context. - 100hermes-agent
Hermes Agent is Nous Research's open-source self-improving AI agent: a terminal and messaging-gateway agent that saves memories, writes and patches its own skills from experience, and searches its past sessions. Use when a user asks to install or configure Hermes Agent, pick its… - 86hermes-box-diagnosis
Use when hermes-agent loops or its memory is full. - 96hermes-agent-factory
Use when creating or cloning a Hermes agent profile.