Introduction¶

Those building IM bots or web assistants often encounter the same problem: the conversation flows in one turn, but the next turn sees a complete loss of memory. The common approach is to stuff the last few rounds of dialogue into the context, or to store chat logs in a file and search for the raw text the next time. The former loses memory if the window is too short, while the latter retrieves the raw text, and the bot won’t judge whether it remembers a specific event clearly, nor will it keep a memory for months just because the user was aggressive on that day.

hippocampus_22 is a memory plugin in the DSH community, maintained by kianajunjie, currently holding 2 stars on GitHub. Its approach isn’t “store chats in a database,” but rather mimics the hippocampus’s function for memory: Event Encoding → Consolidation → Forgetting → Associative Recall → Metamemory. Memory is stored in a local SQLite file—no upload, no internet, no vector database. It can be used as a library during development or operated directly via CLI.

Below is an introduction to what it is, the capabilities it offers, how to install it in DSH, and what scenarios it is suitable for.

I. Positioning & Origin¶

One-sentence positioning: This is an emotional memory layer for long-running companion bots, responsible for processing each round of dialogue into structured memory with emotional weights and recalling it in the next round based on rules.

It is derived from dsh-hippocampus v0.3.1 (MIT) by the same author; the current package version is 0.2.0, licensed under MIT. The derivation and attribution details are written in the repository’s NOTICE file, and redistribution requires keeping LICENSE and NOTICE.

The technical requirement is Node.js >= 22.5, with zero dependencies. It uses only the built-in node:sqlite and does not install any third-party packages.

II. Core Capabilities¶

The capabilities listed in the README are as follows, all of which can be directly verified:

• Event Memory: Each turn of dialogue is processed into “who, when, what happened, what emotion,” rather than storing the raw text.
• Emotion-Weighted Forgetting: Days when the user was angry or touched can last for months, while ordinary days fade quickly.
• Certainty: Each memory carries a three-level tag: “clearly remember,” “probably remember,” or “only remember this happened.” The bot won’t pretend to be certain.
• Contradiction Handling: Facts automatically become invalid once the user changes their mind (e.g., address changes from Chengdu to Hangzhou), avoiding self-contradiction.
• Relationship Layer: Maintaining dimensions like intimacy, trust, and unresolved issues for each user; these fade if the user doesn’t appear for a long time and are resolved once the relationship is repaired.
• Facts / Chapters / Skills / Gaps: Where they live, which period they are in, how they do things, and “what I don’t know”; the bot can proactively ask about things it doesn’t know.
• User Isolation: User A cannot see User B’s memory; group chats cannot access private chat memories.
• Zero Dependencies: Only depends on Node’s built-in SQLite.

Compared to v0.1.0, v0.2.0 added several maintenance capabilities: health for memory health checks, port for memory import/export, report for human-readable archive export, and forget for conditional forgetting. The roadmap also lists memory visualization panels and multi-device sync, which are currently not implemented.

III. How Memory Flows¶

The entry channel can be a QQ bridge, IM, web, or other software. The first step is identity mapping: the identities table ensures “one person = one subject,” allowing recognition across channels.

The subsequent flow is:

1. handleTurn() identifies the user, assembles the context, and performs a recall.
2. Memory falls into layers: events, relations, facts, chapters, skills, gaps.
3. context() organizes the recall results into system prompt blocks and returns them to the upper layer.

The recall methods are in src/recall.mjs. According to the README, the method is “literal matching + graph diffusion + certainty”; specific implementation details are in docs/architecture.md.

IV. Installation & Activation¶

To install as a DSH plugin, the official installation command from the README is:

dsh plugin --profile web add github:kianajunjie/hippocampus_22

The command above corresponds to both IM and web usage modes. It is worth noting that the plugin runs with the permissions of the current dsh process; its ability to read files, access the network, and execute commands depends on how you launched dsh. It is recommended to review the source code and LICENSE before installation.

If you want to run it first to see the effect, you can use the CLI directly. hippo is the command-line entry point provided after installation (the bin in the package defines both hippocampus-22 and hippo):

npm i -g hippocampus-22
hippo demo

demo writes a few old events with emotions, runs a forgetting pass, and then performs a recall to demonstrate the behavior that “emotional weight makes old memories last longer.” This demo does not require an API Key.

V. What the CLI Can Do¶

After installation, use the hippo command directly. Common operations include:

hippo encode --turns <file.json>   # Batch encode dialogue into events
hippo replay                       # Consolidation: merge near-duplicates + emotional decay
hippo recall "腿疼"                # Recall (with certainty)
hippo context --subject 主人 "..."  # Directly view the block that will be stuffed into the prompt this round
hippo remember "…" --pin           # Actively remember a fact, --pin means it never decays
hippo list 20 | audit | stats       # View memory / view invalidation records / view statistics
hippo rel 主人 | rel-shift 主人 intimacy:1 why:吵架
hippo fact-add 主人 住在 杭州 | facts 主人

If you just want to temporarily verify behavior, hippo context is quite useful: given a subject and an input, it prints the block that will be stuffed into the system prompt for this turn, allowing you to see the recall results and certainty directly.

VI. Integrating as a Library or HTTP Service¶

If you don’t want to use the DSH plugin shell, you can also use it as a standalone JS library:

import { createHippocampus } from 'hippocampus-22'

const hip = await createHippocampus({ apiKey: process.env.DEEPSEEK_API_KEY })

// Every message comes in: identify user → assemble prompt block → recall
const r = await hip.handleTurn({ channel: 'qq', externalId: msg.user_id, text, reply })
// r.context is stuffed into the system prompt, r.recall is the recall result

// Consolidate once a day: merge near-duplicates, decay by emotion, write a summary
await hip.replay()

This is the typical deployment method: call handleTurn() inside message callbacks to get context and splice it into the system prompt; call replay() in a scheduled task for consolidation.

For server deployment, you can also start an HTTP service, which can be accessed by any language:

import { createMemoryServer } from 'hippocampus-22/http'
await createMemoryServer({ hip, port: 7717, token: 'secret' })

curl -s localhost:7717/context -H 'authorization: Bearer secret' \
  -H 'content-type: application/json' \
  -d '{"channel":"telegram","externalId":"42","text":"我腿疼"}'

The interface is very thin, simply retrieving the current turn’s prompt context. The example above changes channel to telegram, showing that the channel field can be specified arbitrarily, while identity is unified via externalId mapping.

VII. Suitable Scenarios & Boundaries¶

Who is it for:

• Those writing long-running companion or private chat bots who need cross-session memory.
• Those who want memory to stay on the local machine and don’t want to introduce vector databases or external databases.
• Scenarios requiring multi-user isolation in IM bridging.

Scenarios not suitable:

• Scenarios requiring strict full-text search or semantic fuzzy search. Its recall is literal matching plus graph diffusion, does not provide vector retrieval, and the README does not promise semantic recall.
• Scenarios requiring cross-device real-time sync. Multi-device sync is listed on the roadmap but is not yet implemented.

A few other points to note: handleTurn requires DEEPSEEK_API_KEY because event encoding is extracted by an LLM; demo does not need a key. The project is a derivative; the attribution chain is in NOTICE, so please check the license terms before commercial use or redistribution. Spend a few minutes reading the source code before installation, especially the fact that it runs with the current dsh process permissions.

VIII. One-Sentence Recap¶

hippocampus_22 extracts “companion bot memory” from the practice of “storing chat logs” and replaces it with a layer that has emotional weights, certainty, automatic forgetting, and admits when it doesn’t remember clearly. Storage is a local SQLite file with zero dependencies. If your bot needs cross-session private memory and doesn’t want to send the data out, you can install this plugin to try it out.

Directory page: https://www.skillhub.cn/plugins/kianajunjie/hippocampus_22
GitHub: https://github.com/kianajunjie/hippocampus_22