@hiveai/core

Internal library — shared types, schema, parser, and utilities for the hAIve memory system.

This package is consumed by @hiveai/cli and @hiveai/mcp. You do not need to install it directly unless you are building a custom hAIve integration or extending the tool.

What this package provides

Memory schema (Zod)

A single source of truth for the memory frontmatter format:

import { MemoryFrontmatterSchema, MemoryTypeSchema, MemoryScopeSchema } from "@hiveai/core";

// Types
type MemoryType  = "convention" | "decision" | "gotcha" | "architecture" | "glossary" | "attempt";
type MemoryScope = "personal" | "team" | "module";
type MemoryStatus = "draft" | "proposed" | "validated" | "stale" | "rejected" | "deprecated";

Each memory file is a Markdown file with YAML frontmatter:

---
id: 2025-01-15-gotcha-flyway-strict
scope: team
type: gotcha
status: validated
anchor:
  paths:
    - src/main/resources/db/migration
  symbols: []
tags: [flyway, database, migration]
domain: database
author: [email protected]
created_at: "2025-01-15T10:30:00.000Z"
verified_at: "2025-01-20T08:00:00.000Z"
related_ids:
  - 2025-01-15-attempt-modify-existing-migration
expires_when: null
stale_reason: null
---

# Flyway strict mode — never modify existing migrations

...

Parser / Serializer

import { parseMemory, serializeMemory, buildFrontmatter, newMemoryId } from "@hiveai/core";

// Parse a memory file
const memory = parseMemory(rawMarkdown);

// Serialize back to disk
const markdown = serializeMemory(memory);

// Build a new frontmatter object
const frontmatter = buildFrontmatter({
  type: "gotcha",
  slug: "flyway-strict",
  scope: "team",
  paths: ["src/main/resources/db/migration"],
  tags: ["flyway"],
});

// Generate a canonical ID
const id = newMemoryId("gotcha", "flyway-strict"); // "2025-01-15-gotcha-flyway-strict"

Anchor verification

import { verifyAnchor } from "@hiveai/core";

const result = await verifyAnchor(memory, { projectRoot: "/path/to/project" });
// result.stale          — true if anchor paths or symbols no longer exist
// result.reason         — human-readable explanation
// result.possibleRenames — files with the same basename found elsewhere (rename detection)

Literal search

import { tokenizeQuery, literalMatchesAllTokens, literalMatchesAnyToken } from "@hiveai/core";

const tokens = tokenizeQuery("flyway migration strict");
const matches = memories.filter(({ memory }) => literalMatchesAllTokens(memory, tokens));

Token budgeting

import { allocateBudget, estimateTokens, truncateToTokens } from "@hiveai/core";

const slices = allocateBudget(
  [
    { key: "context", text: projectContext, weight: 3, mode: "head" },
    { key: "memories", text: memoriesText, weight: 4, mode: "head" },
  ],
  8000, // max tokens
);

Usage / confidence tracking

import { loadUsageIndex, trackReads, deriveConfidence, isDecaying, DECAY_DAYS } from "@hiveai/core";

const index = await loadUsageIndex(paths);
const usage = getUsage(index, memoryId);
const confidence = deriveConfidence(frontmatter, usage);
// confidence: "authoritative" | "trusted" | "provisional" | "low" | "stale"

const decaying = isDecaying(usage, frontmatter.created_at); // not read in >90 days

Path helpers

import { findProjectRoot, resolveHaivePaths, memoryFilePath } from "@hiveai/core";

const root  = findProjectRoot();            // Walks up from cwd looking for .ai/ or .git/
const paths = resolveHaivePaths(root);
// paths.memoriesDir, paths.teamDir, paths.personalDir, paths.moduleDir, paths.projectContext, ...

const file = memoryFilePath(paths, "team", "2025-01-15-gotcha-flyway", undefined);

Memory file format

Memories are plain Markdown files stored in .ai/memories/<scope>/ and committed to git:

.ai/
└── memories/
    ├── personal/     # Local only — not committed
    ├── team/         # Committed — shared across the team
    └── module/
        └── payments/ # Scoped to a specific module

The frontmatter schema:

| Field | Type | Description | |---|---|---| | id | string | Canonical ID: YYYY-MM-DD-<type>-<slug> | | scope | enum | personal · team · module | | type | enum | convention · decision · gotcha · architecture · glossary · attempt | | status | enum | draft · proposed · validated · stale · rejected · deprecated | | anchor.paths | string[] | File paths this memory is anchored to (staleness detection) | | anchor.symbols | string[] | Symbol names this memory is anchored to | | anchor.commit | string? | Git commit SHA at time of creation | | tags | string[] | Free-form tags | | domain | string? | Business domain (e.g. payments) | | related_ids | string[] | IDs of related memories (auto-expanded in get_briefing) | | created_at | ISO date | Creation timestamp | | verified_at | ISO date? | Last anchor verification timestamp | | stale_reason | string? | Why the memory was marked stale | | expires_when | string? | Condition under which this memory should be deprecated |

License

MIT