fleet-memory/hindsight-docs/docs/developer/api/documents.md

sidebar_position
8

Documents

Track and manage document sources in your memory bank. Documents provide traceability — knowing where memories came from.

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

:::tip Prerequisites Make sure you've installed Hindsight and understand how retain works. :::

What Are Documents?

Documents are containers for retained content. They help you:

• Track sources — Know which PDF, conversation, or file a memory came from
• Update content — Re-retain a document to update its facts
• Delete in bulk — Remove all memories from a document at once
• Organize memories — Group related facts by source

Retain with Document ID

Associate retained content with a document:

# Retain with document ID
client.retain(
    bank_id="my-bank",
    content="Alice presented the Q4 roadmap...",
    document_id="meeting-2024-03-15"
)

# Batch retain for a document
client.retain_batch(
    bank_id="my-bank",
    contents=[
        {"content": "Item 1: Product launch delayed to Q2"},
        {"content": "Item 2: New hiring targets announced"},
        {"content": "Item 3: Budget approved for ML team"}
    ],
    document_id="meeting-2024-03-15"
)

# From file
with open("notes.txt") as f:
    client.retain(
        bank_id="my-bank",
        content=f.read(),
        document_id="notes-2024-03-15"
    )

// Retain with document ID
await client.retain({
    bankId: 'my-bank',
    content: 'Alice presented the Q4 roadmap...',
    documentId: 'meeting-2024-03-15'
});

// Batch retain
await client.retainBatch({
    bankId: 'my-bank',
    contents: [
        { content: 'Item 1: Product launch delayed to Q2' },
        { content: 'Item 2: New hiring targets announced' },
        { content: 'Item 3: Budget approved for ML team' }
    ],
    documentId: 'meeting-2024-03-15'
});

# Retain file with document ID
hindsight retain my-bank --file notes.txt --document-id notes-2024-03-15

# Batch retain directory
hindsight retain my-bank --files docs/*.md --document-id project-docs

Update Documents

Re-retaining with the same document_id replaces the old content:

# Original
client.retain(
    bank_id="my-bank",
    content="Project deadline: March 31",
    document_id="project-plan"
)

# Update (deletes old facts, creates new ones)
client.retain(
    bank_id="my-bank",
    content="Project deadline: April 15 (extended)",
    document_id="project-plan"
)

// Original
await client.retain({
    bankId: 'my-bank',
    content: 'Project deadline: March 31',
    documentId: 'project-plan'
});

// Update
await client.retain({
    bankId: 'my-bank',
    content: 'Project deadline: April 15 (extended)',
    documentId: 'project-plan'
});

# Original
hindsight retain my-bank "Project deadline: March 31" --document-id project-plan

# Update
hindsight retain my-bank "Project deadline: April 15 (extended)" --document-id project-plan

List Documents

View all documents in a memory bank:

# List all documents
documents = client.list_documents(bank_id="my-bank")

for doc in documents:
    print(f"{doc['id']}: {doc['memory_count']} memories")
    print(f"  Created: {doc['created_at']}")
    print(f"  Updated: {doc['updated_at']}")

# With pagination
documents = client.list_documents(
    bank_id="my-bank",
    limit=50,
    offset=0
)

// List all documents
const documents = await client.listDocuments({
    bankId: 'my-bank'
});

documents.forEach(doc => {
    console.log(`${doc.id}: ${doc.memoryCount} memories`);
    console.log(`  Created: ${doc.createdAt}`);
    console.log(`  Updated: ${doc.updatedAt}`);
});

# List documents
hindsight documents list my-bank

# With limit
hindsight documents list my-bank --limit 50

Get Document Details

Retrieve a specific document with its memories:

# Get document
doc = client.get_document(
    bank_id="my-bank",
    document_id="meeting-2024-03-15"
)

print(f"Document: {doc['id']}")
print(f"Original text: {doc['original_text'][:200]}...")
print(f"Memories: {doc['memory_count']}")

# Get with memories
doc = client.get_document(
    bank_id="my-bank",
    document_id="meeting-2024-03-15",
    include_memories=True
)

for memory in doc['memories']:
    print(f"  - {memory['text']}")

// Get document
const doc = await client.getDocument({
    bankId: 'my-bank',
    documentId: 'meeting-2024-03-15'
});

console.log(`Document: ${doc.id}`);
console.log(`Memories: ${doc.memoryCount}`);

// Get with memories
const withMemories = await client.getDocument({
    bankId: 'my-bank',
    documentId: 'meeting-2024-03-15',
    includeMemories: true
});

# Get document
hindsight documents get my-bank meeting-2024-03-15

# With memories
hindsight documents get my-bank meeting-2024-03-15 --include-memories

Delete Documents

Remove a document and all its memories:

# Delete document (removes all associated memories)
client.delete_document(
    bank_id="my-bank",
    document_id="old-meeting"
)

# Bulk delete
for doc_id in ["old-1", "old-2", "old-3"]:
    client.delete_document(bank_id="my-bank", document_id=doc_id)

// Delete document
await client.deleteDocument({
    bankId: 'my-bank',
    documentId: 'old-meeting'
});

// Bulk delete
for (const docId of ['old-1', 'old-2', 'old-3']) {
    await client.deleteDocument({
        bankId: 'my-bank',
        documentId: docId
    });
}

# Delete document
hindsight documents delete my-bank old-meeting

# Confirm deletion
hindsight documents delete my-bank old-meeting --confirm

Document Response Format

{
  "id": "meeting-2024-03-15",
  "bank_id": "my-bank",
  "original_text": "Alice presented the Q4 roadmap...",
  "content_hash": "sha256:abc123...",
  "memory_count": 12,
  "created_at": "2024-03-15T14:00:00Z",
  "updated_at": "2024-03-15T14:00:00Z",
  "metadata": {}
}

Use Cases

Meeting Notes

# Store meeting notes with date-based IDs
client.retain(
    bank_id="team-memory",
    content=meeting_transcript,
    document_id=f"meeting-{date.today()}"
)

Documentation

# Store docs with version tracking
for file in docs_dir.glob("*.md"):
    client.retain(
        bank_id="docs-memory",
        content=file.read_text(),
        document_id=f"docs-{file.stem}-v{version}"
    )

Conversation History

# Store chat history with session IDs
client.retain(
    bank_id="chat-memory",
    content=conversation,
    document_id=f"session-{session_id}"
)

Next Steps

• Entities — Track people, places, and concepts
• Operations — Monitor background tasks
• Memory Banks — Configure bank settings