ekg

name	ekg
description	Use this skill to supplement memory - both looking for and using memory to understand how to do things, and the state of tasks.
model	inherit

ekg Skill — Emacs Knowledge Graph

ekg is an Emacs package (source) for taking and retrieving notes, backed by a sqlite database. It should be used as a form of agent memory, and it may also be used by users for their notes as well.

Here's how to use it from the command-line. Each script calls emacsclient so the user must have run M-x server-start on their emacs, as well as loaded the ekg package.

Setup: Locating the Scripts

The command-line scripts live in the agent_tools/ directory of the ekg package. Since Emacs packages aren't normally on $PATH, resolve the directory at the start of any session by asking Emacs where ekg is installed:

EKG_DIR=$("${EMACSCLIENT:-emacsclient}" --eval \
  '(file-name-directory (locate-library "ekg"))' | tr -d '"')

Then invoke scripts with their full path, e.g. "$EKG_DIR/agent_tools/ekg-read".

If the emacsclient on PATH is not from the same Emacs installation as the running server, set EMACSCLIENT before using these scripts:

EMACSCLIENT="/path/to/matching/emacsclient"

Alternatively, if you prefer, you can add the directory to your $PATH:

export PATH="$EKG_DIR/agent_tools:$PATH"

ekg-add-note

Create a new note.

ekg-add-note --title "Title" --tag tag1 --tag tag2 --note "content" --mode org-mode

• --title TEXT — Note title. Required for org tasks (org/task tag), optional otherwise.
• --tag TAG — Tags (repeatable, at least one required).
• --note TEXT — Note content (required).
• --mode MODE — org-mode (default), markdown-mode, or text-mode. The --note text must be formatted for this mode (e.g. org markup for org-mode, markdown for markdown-mode).
• Returns the numeric note ID on success.
• The note is automatically tagged with agent and the current date (date/YYYY-MM-DD).
• Content is automatically wrapped in LLM output markers.

ekg-read

Read notes by tag, ID, search, or recency.

# By tags (AND logic)
ekg-read --tag tag1 --tag tag2 -n 10 -w 100

# By note ID
ekg-read 31123361376

# Semantic search (uses embeddings)
ekg-read --semantic-search "query string"

# Full-text search
ekg-read --search "query string"

# Latest modified notes
ekg-read --latest -n 5

• -n NUM — Max notes to return (default: 10).
• -w NUM — Max words per note (default: 100).
• Output is JSON: array of objects with id, text, mode, tags, creation_time, modified_time.

ekg-update-tags

Add or remove tags on an existing note.

ekg-update-tags <note-id> --add tag1 --remove tag2

ekg-tags

Search and list tags in ekg.

# List all tags
ekg-tags

# Tags matching a regex
ekg-tags --regex "org/state/.*"

# Tags with a given prefix
ekg-tags --prefix "project/"

# Tags containing a substring
ekg-tags --including "moltbot"

# Tags co-occurring with another tag (notes that have BOTH tags)
ekg-tags --co-tagged prompt

# Combine filters (AND logic)
ekg-tags --prefix "project/" --co-tagged moltbot

• --regex PATTERN — Filter tags matching a regex.
• --prefix PREFIX — Filter tags starting with prefix.
• --including TEXT — Filter tags containing substring.
• --co-tagged TAG — Find tags that appear on notes also tagged with TAG (repeatable, AND logic).

Output is a JSON array of tag strings.

ekg-append-note

Append text to an existing note. Works with any note type (not just org tasks).

ekg-append-note <note-id> --text "text to append"

• <note-id> — The note's ID (required, positional).
• --text TEXT — Text to append (required). The text must be formatted for the note's mode (e.g. org markup for org-mode notes, markdown for markdown-mode notes).

ekg-trash

Soft-delete a note (trash it). Running again on a trashed note permanently deletes it.

ekg-trash <note-id>

ekg-org-add-child

Create a child org task under an existing parent task.

ekg-org-add-child <parent-id> --title "Subtask title" [--note "description"] \
  [--tag extra-tag] [--status TODO] [--mode org-mode] [--property KEY=VALUE]

• <parent-id> — The parent task's note ID (required, positional).
• --title TEXT — Task title/headline (required).
• --note TEXT — Task content/description (default: empty). Text must be formatted for the --mode (e.g. org markup for org-mode, markdown for markdown-mode).
• --tag TAG — Additional tags (repeatable).
• --status STATUS — Task status: TODO, DONE, WAITING, etc. (default: TODO).
• --mode MODE — org-mode (default), markdown-mode, or text-mode.
• --property KEY=VALUE — Set an org property (repeatable). Keys are case-insensitive and stored uppercase.
• Returns the new note's ID on success.
• The org/task tag and state tag are added automatically.

ekg-org-edit

Edit an existing ekg org task. Only specified fields are changed.

ekg-org-edit <note-id> [--title "new title"] [--note "new content"] \
  [--append "additional text"] [--status DONE] \
  [--set-property KEY=VALUE] [--remove-property KEY]

• <note-id> — The task's note ID (required, positional).
• --title TEXT — Set the task title/headline.
• --note TEXT — Replace the task content/body. Text must be formatted for the note's mode (e.g. org markup for org-mode notes, markdown for markdown-mode).
• --append TEXT — Append text to the existing content (cannot combine with --note). Text must match the note's mode format.
• --status STATUS — Set the status (TODO, DONE, WAITING, STARTED, etc.).
• --set-property KEY=VALUE — Set an org property (repeatable). Keys are case-insensitive and stored uppercase.
• --remove-property KEY — Remove an org property (repeatable).

Tag Conventions

Org Task Tags

With an org/task tag, notes will appear in the org-mode agenda (/ekg:tasks.org) once the user sets it up by adding the file /ekg:tasks.org to the agenda.

Tag	Purpose
org/task	Marks the note as an org task (required)
org/state/todo	Task is pending
org/state/done	Task is complete
org/state/waiting	Task is blocked
org/archive	Archived task (hidden from active agenda)

Org tasks require a --title — this becomes the headline in the org agenda.

Creating an org task

ekg-add-note \
  --title "Implement feature X" \
  --tag "org/task" \
  --tag "org/state/todo" \
  --tag "moltbot" \
  --note "Description of the work to do." \
  --mode org-mode

Marking a task done

ekg-update-tags <note-id> --add "org/state/done" --remove "org/state/todo"

Archiving a completed task

ekg-update-tags <note-id> --add "org/archive"

Prompt Co-Tags

Notes tagged with prompt plus other tags act as injected instructions. This is used by the built-in ekg agent, but as an outside agent, you also need to retrieve relevant prompts (if there are any) and use them before performing any significant action.

Example: A note tagged prompt + slack should inject its instructions into any agentic use of slack.

Creating a prompt note

ekg-add-note \
  --tag "prompt" \
  --tag "slack" \
  --tag "moltbot" \
  --note "Always reply in threads in Slack channels, never top-level." \
  --mode markdown-mode

To find all tags that have prompt co-tags:

ekg-tags --co-tagged prompt

To see all prompt notes:

ekg-read --tag "prompt" -n 20 -w 200

General Tags

• agent — Automatically added to all notes created via ekg-add-note.
• date/YYYY-MM-DD — Automatically added with the current date.
• Project-specific tags (e.g., project/ekg, slack) for organization.

Advanced: Direct Emacsclient

For operations not covered by the scripts, you can call elisp directly:

# Set a property on a note
emacsclient --eval '(progn
  (let ((note (ekg-get-note-with-id NOTE_ID)))
    (setf (ekg-note-properties note)
          (plist-put (ekg-note-properties note) :org/deadline TIMESTAMP))
    (ekg-save-note note)
    "done"))'

# Check a note's properties
emacsclient --eval '(ekg-note-properties (ekg-get-note-with-id NOTE_ID))'

# Get all org tasks as org-mode text
emacsclient --eval '(ekg-org-generate-org-content)'

Key properties for org tasks:

• :titled/title — List containing the title string (e.g., (list "My Task"))
• :org/parent — Parent task note ID (for subtasks)
• :org/deadline — Unix timestamp integer
• :org/scheduled — Unix timestamp integer

Recommended Agent Workflow

1. When starting work on something: Create an org/task + org/state/todo note (add your own tag, e.g., claude) so it shows up in the org agenda.
2. When finishing: Update the tag to org/state/done.
3. For reusable instructions: Create prompt co-tagged notes so they get injected into future relevant tasks.
4. For general knowledge: Create regular notes with descriptive tags.
5. Always search first: Before creating notes, check if relevant ones already exist with ekg-read. Before doing an action, check to see if any notes co-tagged with the prompt tag works.