Auto Classification

robotmem automatically classifies every memory at write time using a pure regex-based L0 engine. No LLM dependency — sub-millisecond execution.

Pipeline Overview

learn(insight="grip_force=12.5N works best because sensor was calibrated")
         │
         ├── classify_category()
         │   Regex first-match → "root_cause" (matched "because")
         │
         ├── estimate_confidence()
         │   Base 0.80 + signals → 0.90
         │   (causal +0.05, backtick +0.05)
         │
         ├── extract_scope()
         │   → {scope_files: [], scope_entities: ["grip_force"]}
         │
         ├── classify_tags()
         │   Multi-label regex → ["root_cause", "observation"]
         │
         └── build_context_json()
             Merge user context + source marker

Category Classification

Priority Order

Categories are matched in strict priority order — first match wins:

Priority High ─────────────────────────────── Priority Low

constraint → preference → worldview →
tradeoff → root_cause → decision → revert →
pattern → architecture → config →
postmortem → gotcha → self_defect →
observation_debug → observation_code → observation →
code (default fallback)

Category Rules

Protected Categories

Three categories are marked as "protected" — they are never consolidated and never time-decayed:

Bilingual Matching

All patterns support both English and Chinese:

# constraint pattern (excerpt)
r"(?:must\s+(?:always|never|not)|(?:必须|禁止|不[允准许]许|强制|绝不|一定要))"

# root_cause pattern (excerpt)
r"(?:root\s*cause|caused?\s*by|because|原因|根因|导致|问题出在|之所以|是因为|由于)"

Confidence Estimation

The confidence score indicates how reliable a memory is, based on content richness signals.

Formula

base = 0.80
+ 0.05 if file path detected (e.g., "src/search.py")
+ 0.05 if code reference detected (backticks or function calls)
+ 0.05 if causal language detected ("because", "caused by", etc.)
+ 0.05 if context JSON provided (> 20 chars)
= cap at 0.95

Signal Detection

Confidence Range

Scope Extraction

The scope extractor identifies referenced files, entities, and modules from the memory text.

File Path Detection

# Regex matches paths like: src/robotmem/search.py, /etc/config.yaml
_FILE_PATH_RE = re.compile(
    r"(?:^|[\s\"'`(,])(/?\w[\w./-]*\.(?:py|rs|js|ts|tsx|go|md|toml|yaml|yml|json|sql|sh|css|html))"
)

Supported extensions: .py, .rs, .js, .ts, .tsx, .go, .md, .toml, .yaml, .yml, .json, .sql, .sh, .css, .html

Entity Detection

Two extraction methods:

1. Backtick entities: `ClassName`, `function_name()`
2. PascalCase names: CogDatabase, FastEmbedEmbedder

# Backtick: `embed_one()` → "embed_one"
_BACKTICK_ENTITY_RE = re.compile(r"`(\w[\w.]*)(?:\(\))?`")

# PascalCase: CogDatabase → "CogDatabase"
_PASCAL_CASE_RE = re.compile(r"\b([A-Z][a-z]+(?:[A-Z][a-z]+)+)\b")

Module Inference

Modules are inferred from file paths:

# "src/robotmem/ops/search.py" → module "ops"
# (parent directory, excluding src/lib/app/tests)

Scope Output

{
    "scope_files": ["src/robotmem/search.py"],
    "scope_entities": ["embed_one", "CogDatabase"],
    "scope_modules": ["robotmem"]
}

Tag Classification

Tags provide multi-label classification — a single memory can have multiple tags.

Process

def classify_tags(text, context_json=None):
    tags = []
    # 1. Match ALL regex patterns (not just first)
    for category, pattern in _CATEGORY_PATTERNS:
        if pattern.search(text):
            tags.append(category)

    # 2. Extract scenario_tags from context JSON
    if context_json:
        ctx = json.loads(context_json)
        for tag in ctx.get("scenario_tags", []):
            if tag in VALID_TAGS:
                tags.append(tag)

    # 3. Fallback
    if not tags:
        tags.append("code")

    return tags

Key difference from classify_category(): - classify_category() → first match (single label) - classify_tags() → all matches (multi-label)

Context-Based Tags

Tags can also be injected via the context JSON:

{
    "scenario_tags": ["debug", "concurrency", "pattern"]
}

These are validated against the VALID_TAGS whitelist (50+ tags) before insertion.

Tag Taxonomy

The tag system uses a 9-dimension hierarchical tree with 50+ tags:

metacognition          ← reasoning, cognitive_bias, decision_framework,
│                        systems_thinking, risk_thinking, worldview, decision
│
capability             ← build, debug, design, review, explain, optimize,
│                        plan, architecture, code
│
domain                 ← cs_fundamentals, ai_ml, finance, business,
│                        cross_domain, config, observation, observation_code,
│                        observation_debug
│
technique              ← patterns, anti_patterns, recipes, language_specific,
│                        pattern
│
timing                 ← when_to_start, when_to_stop, when_to_switch
│
boundary               ← tradeoff, not_applicable, diminishing_returns,
│                        constraint
│
experience             ← war_story, postmortem, gotcha, root_cause, revert
│
self_defect            ← hallucination, sycophancy, overengineering,
│                        no_verification
│
reflection             ← accuracy_calibration, behavior_rule, blind_spot,
                         preference

Dimension Prefix

Each tag maps to a human-readable dimension prefix for display:

dimension_prefix("gotcha")       # → "[经验/踩坑]"
dimension_prefix("architecture") # → "[能力/架构设计]"
dimension_prefix("metacognition")# → "[元认知]"  (root node)

Tag Storage

Tags are stored in the memory_tags table:

Primary key: (memory_id, tag) — no duplicate tags per memory.

Tag Metadata

The tag_meta table maintains the taxonomy hierarchy:

This table is automatically synced from TAG_META_TREE at database initialization.

Context JSON Builder

The build_context_json() function merges user-provided context with automatic metadata:

def build_context_json(insight, context):
    result = {"source": "learn_tool"}

    if context:
        parsed = json.loads(context)
        if isinstance(parsed, dict):
            result.update(parsed)  # Merge user fields
        else:
            result["user_context"] = context  # Store as-is

    return json.dumps(result)

This ensures every memory has at least a source field for provenance tracking.

Path Normalization

File paths extracted by scope are normalized for consistency:

def normalize_scope_files(files, project_root=None):
    """Absolute → relative, deduplicated, sorted"""
    # /Users/jia/project/src/foo.py → src/foo.py

This prevents duplicate entries when the same file is referenced with both absolute and relative paths.

Design Principles

1. Pure regex, no LLM: Sub-millisecond execution, deterministic, no hallucination risk
2. First-match priority: Categories have strict ordering — safety constraints always win
3. Multi-label tags: A memory can be both root_cause and observation
4. Bilingual: All patterns work for both English and Chinese text
5. Graceful fallback: Unknown text defaults to code category with 0.80 confidence
6. Controlled vocabulary: All tags are validated against a whitelist — no free-form tagging