DAG-FS API Reference

Complete API documentation for DAG-FS filesystem functions

Types

typedef unsigned long pattern_id_t;  // Pattern identifier
typedef unsigned long tag_id_t;       // Tag identifier

Initialization

dagfs_init

void dagfs_init(void);

Description: Initialize the DAG-FS filesystem. Called automatically during Brain Controller initialization.

Operations:

  • Clears pattern storage (0x300000 - 0x3FFFFF)
  • Clears index storage (0x400000 - 0x4FFFFF)
  • Initializes pattern counter to 0
  • Initializes next pattern ID to 1

Note: This function is called automatically and should not be called manually.

Pattern Operations

dagfs_create_pattern

pattern_id_t dagfs_create_pattern(const char *tags, const void *data, size_t length);

Description: Create a new pattern from data and tags. Stores data as weight configuration.

Parameters:

  • tags - Pointer to tag string (contextual cues, can be NULL)
  • data - Pointer to data to store
  • length - Length of data in bytes

Returns: Pattern ID on success, 0 on error

Errors: Returns 0 if pattern limit (1024) reached

dagfs_read_pattern

void *dagfs_read_pattern(pattern_id_t pattern_id);

Description: Reconstruct pattern from stored weights. Strengthens pattern on access (reconsolidation).

Parameters:

  • pattern_id - Pattern ID to read

Returns: Pointer to reconstructed data, or NULL on error

Side Effects:

  • Increments pattern access count
  • Increases pattern strength (reconsolidation)
  • Strengthens associated weights

dagfs_write_pattern

int dagfs_write_pattern(pattern_id_t pattern_id, const void *data, size_t length);

Description: Update pattern with new data using Hebbian learning (weight updates).

Parameters:

  • pattern_id - Pattern ID to update
  • data - Pointer to new data
  • length - Length of data in bytes

Returns: 0 on success, -1 on error

Side Effects:

  • Updates weight snapshot with new data
  • Increases pattern strength
  • Increments access count

dagfs_delete_pattern

int dagfs_delete_pattern(pattern_id_t pattern_id);

Description: Delete pattern using Long-Term Depression (LTD) - weakens associated weights.

Parameters:

  • pattern_id - Pattern ID to delete

Returns: 0 on success, -1 on error

Side Effects:

  • Weaken weights by ~10% (LTD)
  • Remove tag associations
  • Mark pattern as deleted
  • Decrement pattern count

dagfs_query

pattern_id_t dagfs_query(const char *pattern, size_t length);

Description: Query patterns by tag/context matching.

Parameters:

  • pattern - Query string/tags
  • length - Length of query string

Returns: Pattern ID if found, 0 if not found

Tag Operations

dagfs_add_tag

tag_id_t dagfs_add_tag(pattern_id_t pattern_id, const char *tag);

Description: Associate a tag with a pattern for contextual access.

Parameters:

  • pattern_id - Pattern ID to tag
  • tag - Tag name string

Returns: Tag ID on success, 0 on error

Note: Creates tag if it doesn't exist, reuses existing tag if found.

dagfs_query_by_tag

pattern_id_t dagfs_query_by_tag(const char *tag);

Description: Find patterns associated with a specific tag.

Parameters:

  • tag - Tag name to search for

Returns: Pattern ID if found, 0 if not found

Note: Returns first matching pattern. Future enhancement: return list of patterns.

Pattern Completion

dagfs_complete_pattern

int dagfs_complete_pattern(pattern_id_t pattern_id, const void *partial_input,
                           size_t input_length, void *output, size_t output_size);

Description: Complete a pattern from partial input (like brain memory recall). Runs forward pass to reconstruct full pattern.

Parameters:

  • pattern_id - Pattern ID to complete
  • partial_input - Partial input data
  • input_length - Length of partial input
  • output - Buffer for completed pattern
  • output_size - Size of output buffer

Returns: Bytes written on success, -1 on error

Side Effects:

  • Strengthens pattern (reconsolidation)
  • Increments access count

dagfs_associate_patterns

int dagfs_associate_patterns(pattern_id_t pattern1, pattern_id_t pattern2);

Description: Link two patterns together (create association). Strengthens both patterns.

Parameters:

  • pattern1 - First pattern ID
  • pattern2 - Second pattern ID

Returns: 0 on success, -1 on error

Side Effects:

  • Increases strength of both patterns
  • Creates association link

Pattern Information

dagfs_get_pattern_info

int dagfs_get_pattern_info(pattern_id_t pattern_id, unsigned long *strength,
                          unsigned long *access_count, unsigned char *state);

Description: Get information about a pattern (strength, access count, state).

Parameters:

  • pattern_id - Pattern ID to query
  • strength - Output: Pattern strength
  • access_count - Output: Number of times accessed
  • state - Output: State (0=free, 1=active, 2=deleted)

Returns: 0 on success, -1 on error

Error Handling

All functions return error indicators:

  • Pattern ID functions: Return 0 on error
  • Integer functions: Return -1 on error, 0 on success
  • Pointer functions: Return NULL on error

Common error conditions:

  • Invalid pattern ID (0 or out of range)
  • Pattern limit reached (1024 patterns)
  • Tag limit reached (512 tags)
  • Pattern not found
  • Pattern already deleted

Assembly Interface

All functions are implemented in x86-64 assembly and follow System V ABI:

  • Arguments: RDI, RSI, RDX, RCX, R8, R9
  • Return: RAX (integer/pointer) or RAX:RDX (64-bit values)
  • Caller-saved: RAX, RCX, RDX, RSI, RDI, R8-R11
  • Callee-saved: RBX, RBP, R12-R15

See Also