hippocampus

Brain-inspired memory system with dual storage: Chronicle (temporal SQLite+MD) and Monograph (important topics with rich metadata). User-configurable via USE...

Security Scan

The skill mostly matches a local memory tool, but several inconsistencies and broad behaviors (automatic saving, file-scanning defaults, missing dependency declaration, cron/exec setup) make its footprint wider than its description warrants.

Purpose & Capability

The skill claims a local memory system and includes code to read/write files and maintain an SQLite index (coherent). However the Python source imports third-party 'yaml' while the manifest lists no dependencies; that's an incoherence (the skill may fail at runtime or silently rely on an environment package). Also the configuration allows scanning arbitrary paths (FILE_SCAN_PATHS) and an absolute BASE_PATH, which could be used to access files outside the skill's data area — disproportionate to a minimal 'memory example' feature unless explicitly intended.

Instruction Scope

SKILL.md instructs the agent to proactively save and auto-offer saving without explicit user commands, to set up cron/hooks, and to scan configured paths for related files. It also exposes a BEFORE_ANSWER setting that loads monograph content into context before each agent response. These behaviors expand the agent's runtime scope beyond simply responding to direct 'save/recall' commands and could cause automatic reading/writing of user files and automatic inclusion of stored content in replies.

Install Mechanism

No install spec or external downloads are used (instruction-only + included Python script), which lowers supply-chain risk. However the code expects Python packages (yaml) not declared in dependencies; that mismatch is a packaging/instruction inconsistency rather than an install-hostile pattern.

Credentials

The skill requests file read/write/exec permissions (reasonable for a local memory system) but the default config includes FILE_SCAN_PATHS (./workspace) and supports absolute BASE_PATH, so a user or misconfigured setting could cause broad filesystem access. There are no required environment variables, which is appropriate, but the ability to execute scripts and configure cron jobs increases potential impact if the skill is given trust.

Persistence & Privilege

The skill is not always-enabled (always: false) and is user-invocable (normal). It does instruct one-click cron/hooks setup and can be run autonomously per platform defaults; autonomous invocation combined with file scanning and exec permissions increases risk surface and should be considered by the user, but autonomy alone is not a disqualifier.

What to consider before installing

This skill appears to implement a local memory system, but you should be cautious before enabling it: - Missing dependency: the Python script imports 'yaml' (PyYAML) but the skill metadata lists no dependencies. Ensure your environment has required packages or the script may fail. - Review USER_CONFIG.md before first use: change AUTO_SAVE to false and set FILE_SCAN_PATHS to a safe directory (or empty) until you confirm behavior. By default it may scan a './workspace' path relative to the skill — verify what that points to in your environment. - Before allowing setup-hooks / setup-all (cron creation) or running init/analyze, inspect the full scripts (scripts/memory.py) yourself or run them in a sandboxed environment. Cron/hooks and exec permission let the skill run code on a schedule and could persist behavior. - The BEFORE_ANSWER/AFTER_ANSWER settings cause stored memory snippets to be loaded around every assistant response; avoid placing highly sensitive data in monograph files unless you understand how those contents will be used and exposed. - If you want higher assurance, ask the maintainer for: a dependency list (requirements.txt), a full audit of any code that writes to crontab or scans absolute paths, and explicit documentation of any external network usage. If you share the rest of memory.py (untruncated), I can re-check for network calls, obfuscated logic, or other red flags.

Brain-inspired memory system with automatic execution

Why Setup Is Needed

Automatic creation is NOT possible because:

1. OpenClaw Hooks: Built-in hooks require manual user configuration
2. Cron Jobs: Cannot be created automatically - requires explicit user authorization
3. Security: OpenClaw requires user confirmation for any automatic tasks

This is by design - it ensures you have full control over what automatic tasks run on your system.

---

Quick Setup (Takes 30 seconds)

After installation, simply say "setup hippocampus" or "configure memory" and I will guide you through the setup process.

What Will Happen

1. I show you all cron jobs that will be created
2. You confirm ONCE by saying "yes" or "confirm"
3. I execute all at once - no repeated approvals
4. Done! Automatic memory saving is enabled

What Gets Created

Job	Schedule	Purpose
hippocampus-autosave	0 */6 * * *	Auto-save every 6 hours
hippocampus-daily-create	0 0 * * *	Create daily memory file
hippocampus-analyze	0 23 * * *	Daily memory analysis

---

Hook Setup (One-Click)

Say "setup hooks" or "/hip setup-hooks" and I will:

1. Show what hooks will be configured
2. Ask for your confirmation once
3. Auto-configure session_start/session_end hooks

---

Manual Setup (Alternative)

If you prefer to do it yourself, here are the commands:

# Step 1: Initialize database (do this once)
python3 scripts/memory.py init

# Step 2: Create cron job
# Copy this command and run it yourself:
cron add --name "hippocampus-autosave" \
  --schedule "0 */6 * * *" \
  --session-target isolated \
  --payload "Run: python3 /path/to/hippocampus/scripts/memory.py autocheck"

# Step 3: Verify
cron list

---

User Configuration

Edit USER_CONFIG.md to customize behavior before or after setup:

# Trigger Settings
ROUND_THRESHOLD = 25       # Save after X rounds
TIME_HOURS = 6            # Save after X hours
TOKEN_THRESHOLD = 10000   # Save to Monograph when tokens > X

# Storage Settings
BASE_PATH = ./assets/hippocampus

# Auto-Save
AUTO_SAVE = true

After editing, run: /hip config reload

---

Special Needs - Before/After Answer Memory

Hippocampus supports special memory types that are loaded before or after each answer:

BEFORE_ANSWER

Memory that should be loaded and considered before each response.

Use cases:

• Language preferences (e.g., "always use English")
• Style guidelines (e.g., "use technical terms")
• User-specific requirements

Example:

BEFORE_ANSWER = language_preferences

Create a monograph topic called "language_preferences" with your requirements.

AFTER_ANSWER

Memory that should be updated after each response.

Use cases:

• Conversation summary updates
• Key points tracking
• Context continuity

Example:

AFTER_ANSWER = conversation_summary

How to Use

1. Create a monograph topic: /hip new language_preferences

2. Add content to it: /hip add Always use English...

3. Edit USER_CONFIG.md:

   BEFORE_ANSWER = language_preferences
   

4. Reload: /hip config reload

---

How Auto-Execution Works

┌─────────────────────────────────────────────────┐
│  TRIGGERS (from USER_CONFIG.md)                │
├─────────────────────────────────────────────────┤
│  • TIME_HOURS: Every 6 hours (cron)            │
│  • ROUND_THRESHOLD: Every 25 rounds             │
│  • TOKEN_THRESHOLD: When tokens > 10,000         │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  autocheck command                              │
│  (checks all thresholds)                        │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  SAVE DECISION                                  │
├─────────────────────────────────────────────────┤
│  • Tokens > TOKEN_THRESHOLD → Monograph         │
│  • Otherwise → Chronicle                        │
└─────────────────────────────────────────────────┘

---

File Structure

hippocampus/                   (SKILL PACKAGE - Git tracked)
├── SKILL.md                   # This file (includes instructions for AI to create examples)
├── USER_CONFIG.md             # User settings (edit this!)
├── skill.yaml                 # Metadata
├── .gitignore                 # Excludes db files
└── scripts/
    └── memory.py              # Core engine

assets/hippocampus/            (USER DATA - Created on first use)
├── chronicle/                 # Temporal memory (empty initially)
│                              # AI will ask to create examples on first use
├── monograph/                 # Important topics (empty initially)
│                              # AI will ask to create examples on first use
└── index/                     # Keyword index (auto-created at runtime)

---

All Commands

Command	Description
/hip setup / /hip setup-all	One-click setup all cron jobs
/hip setup-hooks	Auto-configure session hooks
/hip sync-memory	Sync to MEMORY.md (with confirm)
/hip init	Initialize DB and directories
/hip autocheck	Check triggers and auto-save
/hip new <topic>	Create new monograph
/hip add <content>	Add to current topic
/hip save	Save to chronicle/monograph
/hip recall <keyword>	Recall from memory
/hip important	List monograph topics
/hip search <keyword>	Cross-topic search
/hip query [keyword]	Query chronicle
/hip analyze	Analyze all memory
/hip status	View status
/hip config	Show USER_CONFIG.md
/hip config reload	Reload config
/hip files	Analyze files
/hip collect	Collect related files

---

Important Notes

1. Setup is OPTIONAL: You can use the skill manually without cron
2. YOU control what runs: Cron jobs can be deleted anytime with cron remove
3. Data stays local: All memory files are stored in your workspace
4. USER_CONFIG.md: The ONLY file you should edit

---

Privacy & Security

• No external servers: All data stays on your machine
• No automatic tasks without consent: You must confirm setup
• You can disable anytime: Edit USER_CONFIG.md or remove cron job
• Transparent: All code is readable in memory.py

---

Author

• GitHub: Gabe-luv-Nancy
• Version: 2.1.0
• Created: 2026-03-14