Z1 Memory Palace v3.0

File-based long-term AI memory system with BGE-M3 vector search, metadata filtering, compound scoring, graph-based neighbor expansion, and automated memory m...

Security Scan

The skill's stated zero-infrastructure, local-in-cwd behavior does not match the included scripts which hardcode a single user's absolute vault path and contain path/name mismatches — the package will modify files on disk and may be brittle or surprise you if run without adapting paths.

Purpose & Capability

The skill claims a file-based, zero-infrastructure memory palace you can initialize in the current working directory, but the Python and shell scripts are written to operate on a hardcoded absolute ROOT (/Users/zhouyi0415126.com/ai_matrix/vault/01_core). That means running the provided scripts will not act on the local 'palace/' you create unless you edit the code. This mismatch is unexpected for the claimed purpose and suggests poor packaging or that the code was copied from a single developer's machine.

Instruction Scope

SKILL.md tells the agent/user to create palace/ in the current directory and run pip install FlagEmbedding and the build/query scripts. The code, however, reads/writes manifests, index and graph files under the absolute ROOT path and performs file operations (renaming manifest to a .backup, writing indexes, writing graph_neighbors). auto_maintain.sh also cd's into the hardcoded path and calls scripts under scripts/watchdog/, but the included files are in scripts/ (no watchog subdir). These instructions will either fail or operate on unexpected files; they also perform writes/renames on the user's filesystem (expected for an indexer but important to be explicit).

Install Mechanism

There is no formal install spec; SKILL.md suggests pip install FlagEmbedding. That is a moderate-risk dependency (unknown third-party package) but not inherently malicious. Because this is instruction-only with code files, nothing is automatically written to disk by the registry, but following the instructions will install a third-party Python package and run local scripts that modify files.

Credentials

The skill does not request environment variables or credentials. However, it expects filesystem access to a specific absolute path and will read and write files there (manifests, index, backups, graph). That filesystem access is proportional for a local memory manager, but the hardcoded path is disproportionate to the 'zero-infrastructure' claim and increases risk of accidental modification of unrelated user data if the path is adapted incorrectly.

Persistence & Privilege

The skill is not marked 'always' and does not itself install persistent agents. It contains an auto_maintain.sh that is intended to be run by a LaunchAgent daily (comment only). If a user or integrator wires this into a scheduler, it will perform recurring writes and rebuilds on the hardcoded vault. That persistent operation would increase blast radius, so treat automated scheduling cautiously.

What to consider before installing

Don't run these scripts unchanged. Key risks and actions to consider: - The code hardcodes ROOT = /Users/zhouyi0415126.com/ai_matrix/vault/01_core; it will not operate on a palace/ you create in the current directory. Before running, either change ROOT to a safe test directory or run inside a disposable copy of your repository. - The scripts perform filesystem writes (rename backup of manifest, overwrite index files, write graph JSON). Backup your data first and inspect the manifest/index files before running write operations. - SKILL.md suggests pip install FlagEmbedding (third-party package). Audit that package (source, PyPI page) before installing and consider installing into an isolated virtualenv. - There are path mismatches (scripts call scripts/watchdog/*.py but files are in scripts/). Expect runtime failures and review/normalize paths. - The tool will encode text with a BGEM3FlagModel which may contact remote model services; confirm network behavior and any credentials required by the FlagEmbedding library. - If you want to use this skill, adapt ROOT and script paths to a sandbox/test directory, run dry-runs, and only enable any scheduled/automated runs after verifying effects. If uncertain, ask the author for a repackaged version that uses relative paths or accepts a configurable root path and documents expected side effects.

Memory Palace

A file-based long-term memory system for AI agents, designed to be zero-infrastructure (no Docker, no external services).

Architecture

palace/
├── grand_hall/          # Global navigation, room map, logs
├── chambers/            # Agent-specific knowledge (one per agent)
├── project_rooms/       # Long-running project storage
├── reflection_wing/     # Compiled insights: principles, kernels, patterns
├── dispatch_corridor/   # Task routing and status tracking
├── conflict_room/       # Conflict resolution records
└── archive_basement/    # Cold storage (excluded from default search)

Quick Start

# 1. Initialize palace structure
mkdir -p palace/{grand_hall,chambers,project_rooms,reflection_wing,dispatch_corridor,conflict_room,archive_basement}

# 2. Install BGE-m3
pip install FlagEmbedding

# 3. Build index
python3 scripts/build_index_bge.py --force

# 4. Query
python3 scripts/query_bge.py "your search query"
python3 scripts/query_bge.py --type palace --priority high "query"
python3 scripts/query_bge.py --details "query"   # show sub-scores
python3 scripts/query_bge.py --raw "query"       # pure cosine (v2 compatibility)

Search Scoring

Compound score = 0.5 × Semantic + 0.25 × Recency + 0.25 × Importance

• Semantic: BGE-m3 cosine similarity (clamped to [0,1])
• Recency: 30-day half-life decay based on file mtime
• Importance: priority field mapping (high=1.0, medium=0.6, low=0.3)

Key Scripts

Script	Purpose
build_index_bge.py	Build BGE-m3 vector index with incremental maintenance
query_bge.py	Search with compound scoring, metadata filter, raw mode
graph_router.py	Build 1-hop [[links]] neighbor graph
cold_zone_blinding_patch.py	Exclude archive_basement from search

Index Manifest Format

Each file in the manifest (watchdog_manifest_v1.jsonl) requires:

{"path": "palace/chambers/01_agent/accumulated_knowledge.md", "type": "palace", "priority": "high"}

Fields: path (required), type (for metadata filtering), priority (for importance scoring).

Memory Metabolism

See references/memory_metabolism.md for the full protocol:

• 3-tier upgrade path: Project Room → Reflection Wing → Constitution
• 5 output types: principle card, prompt kernel, failure pattern, thinking path, constitution candidate
• Reverse elimination rules for low-value content