Obsidian plugin

The SmartMemory plugin runs inside Obsidian and sends your markdown notes to your SmartMemory workspace. You install it in Obsidian. There is no cloud storage link to set up.

Once notes are in, you can search and recall them from Obsidian, see the entities SmartMemory found in a note, and browse your workspace graph in a pane.

Before you start

You need a SmartMemory account and an API key, unless you use Local mode (see below). Create the account at www.smartmemory.ai and copy a key from the API Keys section of your settings.

Install

The plugin is not in Obsidian's Community plugin directory yet. Install it with one of these two routes.

With BRAT:

1. Install the BRAT plugin from Obsidian's Community plugins.
2. Open the BRAT settings, choose Add Beta Plugin, paste smartmemory/smart-memory-obsidian, and select Add.
3. Enable SmartMemory under Settings → Community plugins.

Manually:

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Copy them into <your-vault>/.obsidian/plugins/smartmemory/.
3. Enable SmartMemory under Settings → Community plugins.

The plugin needs Obsidian 1.5.0 or later. It is not limited to desktop.

Connect it to your workspace

The first time the plugin loads, it opens a Welcome to SmartMemory window. Pick one of its options: Open settings, Open signup, Connect to local daemon, or I'll set this up later. Until you do, the plugin turns Auto-ingest on save and Auto-ingest on create back on each time it loads, even if you turned them off. Closing the window without a choice does not count, and the window opens again the next time Obsidian loads.

1. In Obsidian, open Settings → SmartMemory.
2. Paste your API key into API key. Text fields save a moment after you stop typing, or when you leave the settings tab. If Obsidian can see a SMARTMEMORY_API_KEY environment variable, it takes precedence over the field.
3. Select Test next to Test connection. The status bar dot is green when the plugin is connected, orange while it is syncing, and red when it is disconnected.

Leave Workspace ID override (under Advanced) blank unless you belong to several workspaces and want a specific one. When it is blank and you use the hosted service, the plugin asks the API for your default workspace and saves it.

The plugin stores your API key in plain text in its data.json file, inside <your-vault>/.obsidian/plugins/smartmemory/. If you sync your vault with git, add that file to .gitignore.

Bring your notes in

There are three ways to send notes.

Ingest one note

Open the note and run the command palette entry SmartMemory: Ingest current note.

Ingest a folder

Run SmartMemory: Ingest folder of current note. It sends the markdown notes in the folder of the note you have open, and in its subfolders, apart from notes inside your Exclude folders list. Run it from a note at the top level of your vault to send the whole vault apart from those folders. When it finishes, it reports how many notes were ingested, how many failed, and how many were skipped because they are empty or in an excluded folder.

Let auto-ingest do it

Auto-ingest on save and Auto-ingest on create are on by default. With Auto-ingest on save on, the plugin sends a markdown note after you change it. With Auto-ingest on create on, it sends a new markdown note after you create it. Each send waits for a pause, five seconds by default, so the plugin does not send on every keystroke. Changes made while a folder ingest is running are not sent automatically. Notes in excluded folders are never sent automatically.

To stop automatic sends, turn both settings off after you have made a choice in the welcome window.

What gets sent

• The note's text. The plugin sends the text below the frontmatter block, the note's path in your vault, and an origin of import:obsidian. If a note has no text below its frontmatter, it is not sent. Automatic ingest skips it quietly and writes a console message that names the note, and Ingest current note shows a "note is empty" notice.
• An unclosed frontmatter block is sent as text. If the block at the top of a note starts with --- but has no closing --- line, the plugin cannot separate it from the text, and sends the whole note, frontmatter included.
• Frontmatter context, each time the plugin can read it. On each send, the plugin tries to read the frontmatter as OKF (see OKF Portability). When that works, the plugin sends the frontmatter fields with the note as context, including fields SmartMemory does not use, such as a private field you added. Whether it works depends on what the frontmatter contains, and a field the plugin writes back does not guarantee it. Treat everything in the frontmatter of a note the plugin sends as sent.
• An unchanged note is not sent again. If a note's text has not changed since its last send and the plugin still has its link to the earlier memory, it asks the API whether the earlier memory still exists, and sends the note again if that memory is gone.
• An edited note replaces its earlier memory. When the text has changed, the plugin deletes the memory it made before and sends the new version. If the delete fails, the new version is still sent, so an older copy can remain.
• Deleting or renaming a note in Obsidian does not delete its memory. The plugin updates or drops its own link to the note.

What the plugin writes into your notes

• Keep notes OKF-conformant is on by default. After a note is sent, the plugin writes a resource field that links the note to its SmartMemory item, and a type field. The type is the memory type SmartMemory reports, or your existing type, or semantic if there is none. This can replace a type you wrote yourself.
• Write SmartMemory OKF extension is off by default. When it is on, the plugin adds the entities SmartMemory extracted and graph edges to a smartmemory block in the note. This happens after Ingest current note, after an automatic send, and after SmartMemory: Enrich current note. Folder ingest does not do it. This setting does not depend on Keep notes OKF-conformant.
• Fields from an earlier plugin version are rewritten whatever the settings say. If a note has frontmatter fields from an earlier version of the plugin, such as smartmemory_id or smartmemory_entities, the plugin rewrites them into the current fields when Obsidian loads, when it first learns your workspace, and when it writes its fields to that note. Notes in excluded folders are left as they are. A smartmemory_id becomes a resource field once the plugin knows your workspace. Until then it stays as it is.
• Auto-link changes a note when you accept. SmartMemory: Auto-link entities in current note shows a preview. The links you accept are written into the note and also recorded as edges in its smartmemory block, whichever way the extension setting is.

No setting stops the plugin from editing your notes in every case.

Exclude folders

Update the plugin to version 0.2.18 or later for the behavior below. In earlier versions, Exclude folders applied only to the folder command, and auto-ingest, Ingest current note, recall, inline suggestions and the startup rewrite of older plugin fields still reached excluded notes.

Exclude folders lists folder path prefixes, and it starts as templates/, .obsidian/. Notes inside an excluded folder are left alone by the whole plugin. They are not sent by Ingest current note, by the folder command, or by auto-ingest. The plugin does not write its frontmatter fields into them, does not enrich them, and does not use their text for recall queries or inline suggestions. Their note panels show "This note is in an excluded folder" instead of results, and the plugin does not insert links to them or from them. Each skip is written to the developer console with the operation and the note's path, and the commands you run yourself show a notice that the note is in an excluded folder.

How an entry matches:

• Prefixes are matched against the note's path in your vault. Capital letters do not matter, and / and \ count as the same separator.
• An entry with a trailing / matches only that folder and its subfolders. An entry without one, such as private, also matches sibling names that start with it, such as private-notes/. Add the / to avoid that.
• Entries are kept exactly as you type them. Entries such as ., .. or Private/.. do not exclude your whole vault.

Excluding a folder does not delete anything. Memories the plugin already made from those notes stay in SmartMemory, and Danger: purge all Obsidian-origin memories still deletes them. Run that command only if you mean to.

Local mode

The Mode setting can point the plugin at a SmartMemory daemon on your own machine instead of the hosted service. The default address is http://127.0.0.1:9014. In that mode the API key field is hidden and no key is needed.

Graph pane

SmartMemory: Open knowledge graph pane opens a pane where you browse your workspace graph. It shows your workspace, not the note you have open.

Some actions in this pane change your SmartMemory data. The Ground button on an entity looks up that entity's name on Wikipedia.

Update the plugin to version 0.2.17 or later. In earlier versions, pressing Delete or Backspace while nodes were selected in the graph deleted them from SmartMemory with no confirmation, even while you were typing in a note. Version 0.2.17 fixes this. Keys you press in a note or in any text field no longer reach the graph, and Delete and Backspace do not delete anything from this pane.

Commands that delete SmartMemory data

SmartMemory: Danger: purge all Obsidian-origin memories from this workspace deletes every memory whose origin starts with import:obsidian. It also removes the resource and smartmemory fields and the older smartmemory_* fields from every markdown note in your vault, except notes in excluded folders. The plugin forgets its links to those notes but does not edit them.

SmartMemory: Purge empty-content memories (legacy YAML-only ingests) deletes every memory in your workspace that has no text, whatever app created it.

Neither command deletes a note file.

Privacy

• The plugin's requests to SmartMemory go to the API URL in its settings, https://api.smartmemory.ai by default, or to the daemon address in Local mode.
• The Ground button in the graph pane sends an entity's name to Wikipedia. Some buttons, such as upgrade and signup, open a page in your browser.
• The plugin keeps a local data.json in its plugin folder. It holds your settings, a map between note paths and SmartMemory items, a content hash for each sent note, and a map from entity names to the notes for them.

While Obsidian is open, the plugin talks to your workspace in the background, without a command from you. This includes:

• connection and health checks when the plugin loads and when you change settings
• a lookup of your default workspace when Workspace ID override is blank
• checks on the note you are viewing when it is linked to a SmartMemory item: when Obsidian loads, when you switch to it, and on a timer, hourly by default. Show supersession banner turns these off.
• automatic sends, as described above
• reads after a single or automatic send, to pick up what SmartMemory found in the note
• requests from panes you have open, for what they show

Requests also happen when you use a feature. The search pane sends the text you type. SmartMemory: Recall related memories for current note sends your selected text, or the whole note file, frontmatter included, if nothing is selected. It does nothing for a note in an excluded folder. If you turn on Enable inline suggestions, which is off by default, the plugin sends the paragraph you are typing as a search query, unless the note is in an excluded folder.

Troubleshooting

• The status bar dot is not green. Open Settings → SmartMemory, check the API key and API URL, and select Test.
• Ingest says it failed. Ingest current note shows an "ingest failed" notice with the error text. Auto-ingest shows an "auto-ingest failed" notice, and folder ingest counts the note as failed. Fix the cause and run the command again.
• You see an upgrade message. Your workspace has reached a limit. For the note limit, Ingest current note opens a window titled "Free tier note limit reached". A daily limit shows a "daily limit reached" notice.
• Auto-ingest turned itself back on. Make a choice in the welcome window (see Connect it to your workspace), then turn it off again.
• Questions or bugs. Open an issue at github.com/smartmemory/smart-memory-obsidian/issues.