DOCSEARCHbyAlgolia
Submit Docs

hippo-memory

repository·master·Indexed 20 days ago

https://github.com/kitfunso/hippo-memory

A biologically-inspired memory system for AI agents (version 1.28.0) that mimics hippocampal processes. It utilizes a multi-layered approach consisting of buffer, episodic, and semantic memory with natural decay to prioritize high-value lessons over trivia. The system includes a comprehensive benchmarking suite featuring LoCoMo for long-conversation retrieval, LongMemEval for ingestion and generation pipelines, and Micro-eval for deterministic mechanic testing.

Tokens
335.7K
Snippets
883
Records
1.4K
Agent score
72%

What's inside hippo-memory

  1. Understand Hippo's Research Tracks and Product Roadmap

    master

    Hippo's development is organized into several research tracks that distinguish its long-term vision from immediate product commitments. Developers should distinguish between product features and research bets:

    • Track G (Long-horizon ML research): Focuses on the bridge between hippocampal circuits and LLMs. These are research bets (e.g., Knowledge-RLHF, Sleep cycle training pipelines) and are not part of the immediate 90/180-day execution plan. Productization of these items is gated by the volume of the hippo-data-corpus.
    • Track H (Cross-cutting research): Addresses fundamental questions that block architectural decisions, such as goal-aware decay dynamics and conflict resolution under uncertainty.
    • Track I (Generative memory): Aims to move beyond simple retrieval to 'constructive episodic recombination'—allowing the system to generate novel connections (conjectures) between stored memories.

    Note: Research items in Track G are not part of the immediate execution plan and require separate scoping before being productized.

  2. Understand the Hippo Roadmap and Status Legend

    master

    The Hippo Roadmap outlines the development trajectory of the project, transitioning from a local CLI tool to a memory backbone for organizational agents. It categorizes features and research goals using a specific status legend to communicate readiness and priority.

    Status Legend

    • [shipped]: Merged or currently in-flight on a feature branch.
    • [next]: Scoped and ready to start within the next 90 days.
    • [planned]: Committed direction, but specific scoping is still pending.
    • [research]: Open questions requiring investigation before scoping.
    • [grant]: Funded conditional on specific grants (e.g., FAD or AIC-P1).
    • [cut]: Explicit non-goals.
    • [critical]: A priority overlay indicating highest urgency (e.g., [critical, next]).

  3. Understand the current UI architecture and serving method

    master

    The Hippo UI (part of the hippo-brain-observatory package) is a React 19 + Vite + Three.js application.

    • Main Visualization: The LivingMap component in ui/src/views/LivingMap/ serves as the primary visualization engine.
    • Rendering Engine: ui/src/engine/scene.ts uses Three.js with custom particle physics to render nodes.
    • Serving the UI: The application is served via src/dashboard.ts. You can start the SPA and the REST API using the following command:
    hippo dashboard --port 3333
    • Current Theme: The default state is a 'dark observatory' theme using a #0a0c10 background and #7c5cff accents.

  4. Understand the Hippo Roadmap structure

    master

    The Hippo Roadmap is divided into two main parts to track different types of development:

    1. Part I - Grant-Tied Deliverables: Tracks work organized by funding status. Items are tagged as:
      • [Committed]: Shipped regardless of grant outcome.
      • [Grant: FAD]: Conditional on Frontier AI Discovery award.
      • [Grant: AIC-P1]: Conditional on AI Champions Frontier AI Phase 1 award.
      • [Phase 2]: Planned follow-on work.
      • [Speculative]: Exploratory work with no firm date.
    2. Part II - Canonical Execution Roadmap: The engineering execution plan covering tracks, benchmarks, schema migrations, and testing commitments.

    For architectural principles, refer to PLAN.md. For research lineage, refer to RESEARCH.md.

  5. Understand the v0.39.0 Security Hardening and GDPR Path A Plan

    master

    The v0.39.0 release focuses on security hardening and implementing 'GDPR Path A' for data redaction. Key objectives include:

    • Cross-tenant security: Implementing strict tenant checks across the API and MCP (Model Context Protocol) tools to prevent cross-tenant data access.
    • GDPR Path A (Data Redaction): When archiving raw memory via archiveRawMemory, the payload_json is redacted to a minimal set of metadata (redacted: true, archived_at, tenant_id, kind, reason) instead of storing the full row.
    • Auth Hardening: Reducing timing leaks in API key validation and implementing bearer token lockdown for all public routes.
    • Slack Ingest Reliability: Closing race conditions in Slack ingestion using the afterWrite hook and improving Dead Letter Queue (DLQ) replay capabilities.
    • Schema Migrations: Sequential migrations (v19 and v20) are required to support new Slack DLQ columns and the GDPR redaction backfill.

  6. What is a Project Brief and how does it work?

    master

    A project_brief is a first-class E2 object in Hippo that serves as a living, repo-scoped summary of a repository's state. Unlike other E2 objects that are tenant-scoped, a brief is keyed by a combination of tenant_id and repo (the directory name segment).

    Key Characteristics:

    • Repo-scoped: It tracks the state of a specific repository.
    • Auto-refreshable: Instead of relying solely on manual updates or LLM summarization, it uses a deterministic assembler to gather recent 'receipts' (memory rows tagged with path:<repo-name>) and render them into a markdown summary.
    • Lifecycle: Briefs move through states: active -> superseded (when a newer version is created) or active -> closed (when retired).
    • Supersede Pattern: To update a brief, you don't just edit it; you perform a supersede operation which creates a new version and marks the old one as superseded.

  7. What is a Policy and how does its lifecycle work?

    master

    A policy is a first-class E2 object representing a named rule or statement that is in force over a specific effective-time range. Policies evolve via supersession, where a newer version replaces an existing one, or they can be closed (retired).

    Lifecycle States

    • active: The policy is currently in force.
    • superseded: A newer version of the policy has replaced this one. The predecessor's valid-time range remains intact, but its transaction status changes.
    • closed: The policy has been retired.

    Bi-temporal Design

    Policies use two time axes:

    1. Valid time (effective time): When the policy is active in the real world. Managed via valid_from (required, defaults to creation time) and valid_to (nullable, represents an open-ended policy).
    2. Transaction time (system time): When the record was created or retired (via created_at and superseded_at).

  8. What is a Hippo Process and how does it evolve?

    master

    A process is a first-class E2 object representing a living process map: a named, ordered list of steps that evolves over time.

    Unlike other objects, a process evolves through a supersede-as-delta lifecycle. Instead of editing an existing process, you create a new version that supersedes the previous one. This creates a version chain (changelog) where each successor contains a change_summary explaining the delta and the full new state of steps.

    Lifecycle States:

    • active: The current version of the process (default on creation).
    • superseded: A version that has been replaced by a newer version. The superseded_by field points to the successor.
    • closed: The process is retired entirely. A process can only be closed if it is currently active.

  9. Overview of the Fact Extraction, DAG Summarization, and Multi-Hop Retrieval architecture

    master

    The Hippo memory architecture is designed to improve retrieval performance (targeting a LoCoMo score increase from 20% to 70%+) through three incremental phases:

    1. Phase 1: Write-Time Fact Extraction: Adds LLM-based fact extraction during the remember flow. Extracted facts are stored as Semantic entries that maintain links to their original episodic memory sources.
    2. Phase 2: DAG Summarization: Builds topic-level Directed Acyclic Graph (DAG) summaries during the consolidation process.
    3. Phase 3: Multi-Hop Retrieval: Implements a two-pass retrieval system to handle complex, multi-hop questions.

    All phases are designed to work alongside existing bio-inspired mechanics such as memory decay, retrieval strengthening, and consolidation.

  10. Timestamp Invariant for Memory and Session Data

    master

    To ensure correct chronological sorting via byte comparison, all timestamp fields in Hippo must follow a strict invariant.

    Supported Fields:

    • MemoryEntry: created, last_retrieved, valid_from, earliest_at, latest_at.
    • SessionEvent, TaskSnapshot, SessionHandoff, etc.

    Invariant Requirement: All timestamps must be stored as canonical Date.prototype.toISOString() output. This means they must be exactly 24 characters, in UTC, with millisecond precision and a trailing Z (e.g., 2026-05-06T00:00:00.000Z).

    Note for Integrators: Any import or process that preserves local-time offsets MUST normalize to UTC ISO format on write to maintain sort integrity.

  11. Understand SSO and SCIM stub limitations

    master

    In the current version (v1.x), SSO (Single Sign-On) and SCIM (System for Cross-domain Identity Management) features are implemented as stubs. If you attempt to call these functions, they will throw a NotImplementedError. These features are explicitly deferred to the v2 multi-tenant release and are currently only present as hook points in the codebase.

    // Attempting to use these will result in a NotImplementedError
// tracked for v2 multi-tenant

import { ssoLogin, scimProvisionUser, scimDeprovisionUser } from 'src/sso';

// Example of what triggers the error:
ssoLogin({ provider: 'oidc', token: '...' });

  12. Ensure Accessibility for Color-coded Data

    master

    Because color is used to convey information (tags/paths), the system provides non-color channels to support users with color-vision deficiency:

    1. MemoryTooltip: When in tag or path mode, if a memory has a qualifying tag, the tooltip displays a color: <tag> line at the top of the body.
    2. Drawer: A new "tag" column is conditionally rendered in the Drawer component when colorMode is tag or path. This column is keyboard-navigable (rows have tabIndex={0}) and provides the primary equivalent-access surface for the data.
    3. BottomBar: The affordance key (e.g., size = ... · color: <mode>) is updated to show the active color mode when it is not set to layer.