Noosphere Memory for Kilo Code

Kilo Code plugin for Noosphere memory integration.

It provides:

• prompt-time auto-recall through POST /api/memory/recall
• optional idle auto-save through POST /api/memory/save
• manual tools for status, recall, topic lookup, and draft memory saving

Before you start

You need two things before this plugin will do anything useful:

1. A reachable Noosphere instance. The plugin defaults to http://127.0.0.1:6578. For a local install, the cleanest path is the repository's Docker Compose stack — it provisions just Noosphere, without pulling in any other plugin:

   git clone https://github.com/SweetSophia/noosphere.git
   cd noosphere
   cp noosphere.env.example .env
   # Edit .env: POSTGRES_PASSWORD, NEXTAUTH_SECRET, NOOSPHERE_ADMIN_PASSWORD,
   # and NOOSPHERE_BOOTSTRAP_API_KEY. Generate strong values, for example:
   # openssl rand -hex 32
   # printf 'noo_%s\n' "$(openssl rand -hex 32)"
   docker compose -f docker-compose.noosphere.yml up -d

   The bootstrap key is whatever you put in NOOSPHERE_BOOTSTRAP_API_KEY and has full ADMIN scope. To point at an existing Noosphere instead, set baseUrl in the plugin options (see Configuration).

   Note: the repository also ships install-openclaw.sh, a one-shot installer that provisions Noosphere plus the OpenClaw plugin. Use it if you intend to run both tools; skip it if you only want Kilo Code.

2. A Noosphere API key for this tool. The plugin will refuse to start without one. Create a tool-scoped key (named after the tool, e.g. kilocode) in the Noosphere admin UI at:

   https://<your-noosphere-host>/wiki/admin/keys

   Admin login is required. The local Docker Compose install creates an [email protected] admin account whose password is in .env as NOOSPHERE_ADMIN_PASSWORD. See Secrets below for which permissions the key needs and where to put it.

Install

npm install -g @sweetsophia/kilocode-noosphere-memory

Add it to ~/.config/kilo/kilo.json:

{
  "plugin": [
    "@sweetsophia/kilocode-noosphere-memory"
  ]
}

You can also install it with Kilo's plugin command:

kilo plugin @sweetsophia/kilocode-noosphere-memory --global

Or configure it with explicit options:

{
  "plugin": [
    [
      "@sweetsophia/kilocode-noosphere-memory",
      {
        "baseUrl": "http://127.0.0.1:6578",
        "autoRecall": true,
        "autoRecallInjectOn": "first",
        "autoSave": false
      }
    ]
  ]
}

Secrets

Do not put real Noosphere API keys in repo files.

Set the key in the environment used to launch Kilo Code:

export KILOCODE_NOOSPHERE_API_KEY="noo_..."

Use KILOCODE_NOOSPHERE_* variables on machines that also run Opencode, OpenClaw, or Hermes. Generic NOOSPHERE_* variables are still supported as backward-compatible fallbacks.

The key needs:

• READ for recall and topic lookup
• ADMIN for full status information (falls back to /api/health automatically if key lacks ADMIN)
• WRITE for manual saves and auto-save

Configuration

| Option | Environment Variable | Default | Description | | --- | --- | --- | --- | | baseUrl | KILOCODE_NOOSPHERE_BASE_URL or KILOCODE_NOOSPHERE_URL; fallback: NOOSPHERE_BASE_URL or NOOSPHERE_URL | http://127.0.0.1:6578 | Noosphere deployment URL. | | apiKey | KILOCODE_NOOSPHERE_API_KEY; fallback: NOOSPHERE_API_KEY | none | Noosphere API key. Prefer the tool-specific environment variable. | | timeoutMs | KILOCODE_NOOSPHERE_TIMEOUT_MS; fallback: NOOSPHERE_TIMEOUT_MS | 5000 | Request timeout. | | autoRecall | KILOCODE_NOOSPHERE_AUTO_RECALL; fallback: NOOSPHERE_AUTO_RECALL | true | Enable prompt-time recall injection. | | autoRecallInjectOn | KILOCODE_NOOSPHERE_AUTO_RECALL_INJECT_ON; fallback: NOOSPHERE_AUTO_RECALL_INJECT_ON | first | first or always. | | autoRecallMax | KILOCODE_NOOSPHERE_AUTO_RECALL_MAX; fallback: NOOSPHERE_AUTO_RECALL_MAX | 5 | Maximum recalled memories. | | autoRecallTokenBudget | KILOCODE_NOOSPHERE_AUTO_RECALL_TOKEN_BUDGET; fallback: NOOSPHERE_AUTO_RECALL_TOKEN_BUDGET | 1200 | Prompt injection token budget. | | autoSave | KILOCODE_NOOSPHERE_AUTO_SAVE; fallback: NOOSPHERE_AUTO_SAVE | false | Enable idle auto-save. | | autoSaveDebounceMs | KILOCODE_NOOSPHERE_AUTO_SAVE_DEBOUNCE_MS; fallback: NOOSPHERE_AUTO_SAVE_DEBOUNCE_MS | 10000 | Idle debounce before auto-save. | | autoSaveTopicId | KILOCODE_NOOSPHERE_AUTO_SAVE_TOPIC_ID or KILOCODE_NOOSPHERE_TOPIC_ID; fallback: NOOSPHERE_AUTO_SAVE_TOPIC_ID or NOOSPHERE_TOPIC_ID | none | Required for auto-save. | | authorName | KILOCODE_NOOSPHERE_AUTHOR_NAME; fallback: NOOSPHERE_AUTHOR_NAME | Kilo Code | Draft candidate author display name. |

Auto-Recall

The plugin uses Kilo Code's chat.message hook. It extracts the user prompt, calls Noosphere in auto mode, and prepends the returned memory context as a synthetic text part.

Recall runs:

• on the first user message in a session by default
• after compaction
• on every message when autoRecallInjectOn is always

Recalled memory is wrapped in <noosphere_auto_recall> so Noosphere can strip injected context if it is later saved.

Auto-Save

Auto-save is available but disabled by default to avoid unexpected writes from public installs.

To enable it:

export KILOCODE_NOOSPHERE_AUTO_SAVE=true
export KILOCODE_NOOSPHERE_AUTO_SAVE_TOPIC_ID="<topic UUID>"

When Kilo Code emits session.idle, the plugin waits for the configured debounce, extracts the latest user request and assistant response, and saves a draft memory candidate. It skips short and trivial prompts.

Tools

noosphere_status

Checks plugin config and Noosphere memory status.

noosphere_recall

Manual memory search.

Arguments:

• query required
• resultCap optional, 1-10
• tokenBudget optional, 100-2000
• scope optional

noosphere_topics

Lists topics and IDs for use with noosphere_save.

noosphere_save

Saves durable content as a draft memory candidate.

Arguments:

• title required
• content required
• topicId required
• excerpt, tags, restrictedTags, source, confidence optional

Use this for stable project facts, decisions, runbooks, and recurring fixes. Do not save secrets, raw prompt dumps, or transient task chatter.

Development

npm install
npm run typecheck
npm run build
npm pack --dry-run